Night Owl 6/Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso/025a/snp497.zip/SNAP.DOC

Text File | 1991-09-09 | 179KB | 4,938 lines

                                        SNAP!
                         Documentation and Development System
                             for FoxPro, dBASE, Clipper,
                               and Other X-Base Systems


                       Written by Walter J. Kennamer 74025,514



                                ┌─────────┐
                          ┌─────┴───┐     │              (tm)
                        ──│         │o    │──────────────────
                          │   ┌─────┴╨──┐ │  Association of
                          │   │         │─┘  Shareware
                          └───│    o    │    Professionals
                        ──────│    ║    │────────────────────
                              └────╨────┘    MEMBER



                                       License

     Copyright (c) 1991 Walter J. Kennamer. All Rights Reserved.

     You are free to use, copy and distribute SNAP! providing that:

          NO FEE IS CHARGED FOR USE, COPYING OR DISTRIBUTION.

          IT IS NOT MODIFIED IN ANY WAY.

          THIS DOCUMENTATION FILE (UNMODIFIED) ACCOMPANIES ALL COPIES.

     This program is provided AS IS without any warranty, expressed or implied,
     including but not limited to fitness for a particular purpose.

     dBASE II, dBASE III, dBASE IV are trademarks of Ashton-Tate. Clipper is a
     trademark of Nantucket Software.  FoxBASE, FoxBASE+ and FoxPro are
     trademarks of Fox Holdings, Inc.  UNIX is a trademark of AT&T.  Other
     trademarks are the properties of their respective holders.








                             Table of Contents

     Overview  . . . . . . . . . . . . . . . . . . . . . . . . . .   4
          X-Base Dialects  . . . . . . . . . . . . . . . . . . . .   5
          Registration Fee . . . . . . . . . . . . . . . . . . . .   6

     Getting Started . . . . . . . . . . . . . . . . . . . . . . .   7
          Basic Operation  . . . . . . . . . . . . . . . . . . . .   7
          A Tour of the SNAP! Screens  . . . . . . . . . . . . . .   8
          Author and Copyright Holder  . . . . . . . . . . . . . .   8
          Paths  . . . . . . . . . . . . . . . . . . . . . . . . .   8
          Saving and Restoring Default Choices . . . . . . . . . .   9
          Abbreviations  . . . . . . . . . . . . . . . . . . . .    10
          Status Reports . . . . . . . . . . . . . . . . . . . .    10
          Searching the Program Tree . . . . . . . . . . . . . .    11
          dBASE Version? . . . . . . . . . . . . . . . . . . . .    11
          Ignoring Drive Designations  . . . . . . . . . . . . .    11
          Printing SNAP! Documentation . . . . . . . . . . . . .    12
          Using a Mouse  . . . . . . . . . . . . . . . . . . . .    13

     SNAP! Commands  . . . . . . . . . . . . . . . . . . . . . .    14
          Macros . . . . . . . . . . . . . . . . . . . . . . . .    14
          Indirect References  . . . . . . . . . . . . . . . . .    15
          SNAPCODE--Fake Program Statements  . . . . . . . . . .    16
          Multiple Program and Data Directories  . . . . . . . .    17
          Program Narratives . . . . . . . . . . . . . . . . . .    17
          Other SNAP! Directives . . . . . . . . . . . . . . . .    17

     Source Code Formatting Options  . . . . . . . . . . . . . .    19
          File Headings  . . . . . . . . . . . . . . . . . . . .    19
          Indentation  . . . . . . . . . . . . . . . . . . . . .    20
          Capitalization . . . . . . . . . . . . . . . . . . . .    21
          Key Word Expansion and Compression . . . . . . . . . .    22
          Suppressing Blank Lines and Comments . . . . . . . . .    22
          Key Words File . . . . . . . . . . . . . . . . . . . .    23

     Reports and Outputs . . . . . . . . . . . . . . . . . . . .    26
          Controlling the Printer  . . . . . . . . . . . . . . .    26
          Tree Structure Diagram . . . . . . . . . . . . . . . .    26
          File List  . . . . . . . . . . . . . . . . . . . . . .    28
          Database Summary . . . . . . . . . . . . . . . . . . .    28
          Index File Summary . . . . . . . . . . . . . . . . . .    29
          Format File Summary  . . . . . . . . . . . . . . . . .    30
          Report Form Summary  . . . . . . . . . . . . . . . . .    30
          Label Form Summary . . . . . . . . . . . . . . . . . .    31
          Procedure File Summary . . . . . . . . . . . . . . . .    31
          Other Summary Reports  . . . . . . . . . . . . . . . .    31
          Variable Cross-Reference Report  . . . . . . . . . . .    32
          LNK and MAKE files . . . . . . . . . . . . . . . . . .    35
          Batch Files  . . . . . . . . . . . . . . . . . . . . .    36
          Action Diagrams  . . . . . . . . . . . . . . . . . . .    37

                                     2







          Source Code Printout . . . . . . . . . . . . . . . . .    40
          Printing Without Documenting (Reprinting)  . . . . . .    42

     Using SNAP! in a Batch Environment  . . . . . . . . . . . .    43

     Random Notes  . . . . . . . . . . . . . . . . . . . . . . .    44

     Program Limitations . . . . . . . . . . . . . . . . . . . .    45
          Legal Coding that is Prohibited by SNAP! . . . . . . .    45
          Hyphens in Filenames . . . . . . . . . . . . . . . . .    46
          Multiple Procedure Files . . . . . . . . . . . . . . .    46
          Suppressing Color  . . . . . . . . . . . . . . . . . .    46

     Change History  . . . . . . . . . . . . . . . . . . . . . .    47

     Administrative Matters  . . . . . . . . . . . . . . . . . .    51
          Version Numbers  . . . . . . . . . . . . . . . . . . .    51
          Updates and New Versions . . . . . . . . . . . . . . .    51
          How to Get Support . . . . . . . . . . . . . . . . . .    51
          Association of Shareware Professionals . . . . . . . .    52

     Acknowledgements  . . . . . . . . . . . . . . . . . . . . .    53

     Appendix A -- Sample Reports  . . . . . . . . . . . . . . .    54

     Index . . . . . . . . . . . . . . . . . . . . . . . . . . .    78



























                                     3










                                       Overview

     (A short note to the faithful: those of you who have used SNAP! before may
     wish to turn directly to the Change History where new features in version
     5.0 are summarized.)

     SNAP! makes documenting X-Base programs a snap.  SNAP! is designed to
     produce technical documentation for an entire X-Base system.  Its reports
     include:

          Formatted source code listings
          System summary showing lines of code, file statistics, etc.
          Variable cross-reference report
          Tree structure of the system.  The tree optionally can also show
          databases, index files, etc. used by each program.
          List of all files in the system, plus a source reprint file
          Database summary
          Index file summary (including multiple index files)
          Format file summary
          Label form summary
          Report form summary
          Procedure/function file summary
          BIN file summary
          Memory file summary
          Other files summary
          Action diagrams
          Batch files to back up programs, databases, etc.
          Batch file to move SNAP! output files back to the source subdirectory
          For FoxPro 2.0 applications:
               Screen file summary
               Menu file summary
          For Clipper applications:
               Link files (PLINK86, TLINK, MS-LINK)
               Make files

     In addition, on each program file, SNAP! can write a heading showing:

          Program name
          System name
          Author and copyright notice
          Which programs, procedures and functions call this program
          Which programs, procedures and functions this program calls
          Databases used
          Index files used
          Formats used
          Report forms used
          Procedures
          BIN files called or loaded
          Memory files used

                                          4







          Other files used (text files, misc. files, and the like)
          Date and time last modified

     If you wish, all source code headings can also be echoed to a separate
     file.  Additionally, SNAP! can indent your source code and capitalize key
     words to make your code easier to read, understand and maintain.

     Unlike many other X-Base documentation systems, SNAP! documentation is
     system-wide.  In other words, not only can it tell you where variable X was
     used in a particular program, it can cross-reference all occurrences of
     variable X anywhere in the program system you are documenting.  You merely
     enter the "top" program file name, and SNAP! does the rest.  Of course, you
     may also document a single program if you wish.


     X-Base Dialects

     SNAP! fully supports the following dialects of the X-Base language:
          dBASE II
          dBASE III
          dBASE III+
          dBASE IV 1.0

          FoxBASE
          FoxBASE+ 2.1
          FoxPro 1.0
          FoxPro 2.0

          Clipper (releases through Summer '87)

     SNAP! provides limited support for Clipper 5.01.  Unfortunately, Clipper
     has diverged too much from other X-Base dialects to make full support
     practical.  My goal was to make SNAP! work as well as possible with Clipper
     5.0 applications, and at least not break anything.  The following are
     supported:
          STATIC functions (e.g., STATIC FUNCTION foo).
          In-line function declarations (e.g., FUNCTION foo(params...) ).
          Clipper 5.0 key words.
          // comment marks.
          /* */ comments, so long as they are at the beginning of a line, or
               both the comment begin (/*) and comment end (*/) are on the same
               line.
          #include and #define directives (basically, #include is treated just
               like a DO statement and #define is treated like a SNAP! macro
               substitution).
     Code blocks are not supported, but generally do no harm.

     In addition, SNAP! generally handles Force, dbXL, Quicksilver and VP-INFO
     programs pretty well.  However, I do not guarantee that it fully supports
     all features of these products.



                                          5







     Registration Fee

     There isn't one.  SNAP! can be copied and distributed freely, as long as it
     is unchanged and you include this document file unmodified.  I encourage
     you to give copies to your friends and co-workers, to upload them to
     bulletin boards, and to leave them in bus stations.















































                                          6








                                   Getting Started

     First, make a backup copy of your program files.  I have tried to test
     SNAP! on a variety of hardware and software combinations, and there
     shouldn't be any danger, but I would feel awful if anyone lost program
     files due to some curious combination of resident programs, unusual
     equipment and sunspot activity, not to mention (gasp!) "features."  SNAP!
     has been around for several years now and nobody has reported that SNAP!
     has ever corrupted source code, but I would hate for you to be the first.


     Basic Operation

     SNAP! is very easy to use.  If you accept the program's default options,
     you only have to enter the following information on the TopFile screen:

          "Top" file name
          System name
          Author and copyright information
          Paths for program, data, output and SNAP! files

     If you are happy with the defaults, just enter the information on the first
     screen (the System screen), press F10 to see the main menu, then press 'B'
     to begin documenting your system.

     The term "Top File" (spelled and punctuated in a variety of ways) is used
     throughout this documentation to mean the first file in a system--the one
     first invoked.

     You can press F10 to see the main menu.  Its choices largely correspond to
     various option screens.  For example, you set report options on the Reports
     Screen and there is a "Reports" choice on the main menu.

     If you don't want to use the menu, you can save a keystroke or two by using
     the Alt key in combination with the menu choice you want.  For example,
     without pressing F10 to pop up the menu, you can press Alt-R to see the
     Reports Screen, Alt-B to Begin Documenting, Alt-Q to quit and so forth.
     Also, the Ctrl-PgUp and Ctrl-PgDn keys take you to the preceding and
     succeeding screens respectively.

     The line at the bottom of the screen tells you which function keys are
     active.  You can access these functions by pressing the function key or by
     pointing at the description on the bottom of the screen with a mouse.  At
     any point, you can press the F1 key to receive context-sensitive help.
     Help is available for each field.

     The SNAP! system is composed of the following files:
          SNAP.EXE     -- main program file
          SNAP.HLP     -- help file
          SNAP.DOC     -- this documentation file
          DB2WORDS.SNP -- key word file for dBASE II/FoxBASE

                                          7







          DB3WORDS.SNP -- key word file for
                         dBASE III/Clipper/FoxBASE+
          DB4WORDS.SNP -- key word file for dBASE IV/FoxPro
          SNAPPRT.SNP  -- printer definitions
          filename.KEY -- key word files for third-party libraries

     All of these files must be in the same subdirectory, which may be different
     than the subdirectory in which your dBASE source code files are stored.


     A Tour of the SNAP! Screens

     SNAP! has seven main screens on which you can select various combinations
     of options:
          System:   Contains system-level information (system name, author, top
                    file name, etc.).
          Report:   Determines which documentation reports will be generated.
          Format:   Determines source code formatting and action diagram options
                    in effect.
          Xref:          Determines what kinds of words will be in the cross-
                         reference.
          Headings: Determines what goes in a program heading.
          Tree:          Determines what kinds of files will be shown on the
                         tree diagram.
          Print:    Determines source code printing parameters.
          Other:    Other options.

     The next sections highlight a few of the fields that may have hidden
     mysteries.


     Author and Copyright Holder

     Enter the author and copyright holder in these fields.  This information is
     used only in the program headings, and may be omitted if you choose not to
     write program headings (you make that choice on the Format screen).  If you
     enter either author or holder, but not both, SNAP! assumes that they are
     the same.  The copyright date field is large enough to hold dates like
     "1990-1991."


     Paths

     The TopFile menu screen has four fields for path information--the path to
     the source code, data, output and SNAP! files.  Your response should be a
     valid MS-DOS path, with or without drive designation.  It doesn't matter if
     you omit the final backslash (e.g., C:\SNAP is valid, as is C:\SNAP\ or
     \SNAP).

     If the TopFile you specify cannot be found, or if the SNAP! files are not
     where you say they are, SNAP! complains and will not let you begin


                                          8







     documentation.  If the output directory does not exist, SNAP! will create
     it.  If this is a FoxPro 2.0 system, TopFile can be a project.

     If your input and output paths are different, SNAP! will not modify your
     original source code files in any way.  Only the output files will contain
     capitalized key words, indents, headings and so on.

     On the other hand, if the source code and output paths are the same, SNAP!
     adds .BAK extensions to your original input files and creates modified
     output files with the original names.  For example, if one of your input
     programs was named EDIT.PRG, after running SNAP! it will be called EDIT.BAK
     and a new, modified EDIT.PRG will be in the directory.  This scheme works
     fine as long as all your input files have unique names (not counting the
     extension).  Otherwise, all but the last non-unique input file will be lost
     (though the modified output files will still be there).  The best idea is
     never to direct output to the input directory if the first eight characters
     of all of your program files are not unique.

     See the section below on "Multiple Directories" for information about how
     to define more than one data and program directory to SNAP!.  Note that
     SNAP! pays no attention to "SET PATH TO" statements.  SNAP! also cannot
     handle macro substitutions for drives or paths.

     SNAP! never modifies database, index, report form, label form, memory files
     or binary files.

     When SNAP! decides you are about to do something particularly dangerous, it
     may require you to direct output files to a different directory than the
     input files are in.  Some "dangerous" options include expanding or
     compressing key words and eliminating comments from source code.


     Saving and Restoring Default Choices

     As you use SNAP!, you may wish to modify the default values for certain
     fields.  For example, you may want to set the SNAP! path to \SNAP, or the
     author and copyright holder to your name.  Press F5 to save the current
     values of each field.  SNAP! will prompt you for a filename to use for the
     configuration file.

     When you start SNAP!, you can specify the file to use for default values by
     using the /F switch on the command line.  For example, the command:
          SNAP /fc:\foo\bar.baz  (note: no space between '/f' and the filename).
     tells SNAP! to look for a configuration file named 'bar.baz' in the '\foo'
     subdirectory on drive c:.  If it cannot find it, SNAP! will start with
     default values.  When you save the configuration, SNAP! uses the name you
     specified.  If you do not specify a file, SNAP! looks for one called
     CONFIG.SNP in the current directory. If the file you specify does not have
     an extension, SNAP! assumes the extension is '.SNP'.  So the order for
     establishing defaults is:
          1.  A configuration file you specify on the command line
          2.  CONFIG.SNP in the current subdirectory

                                          9







          3.  SNAP! factory default values

     I ordinarily save a separate configuration file for each system I use in
     the same subdirectory with the system.  This is a big help for running
     SNAP! in batch mode (see below) and for keeping subdirectories, filenames,
     etc. straight.

     You can also press F6 to retrieve saved specifications.  Invoking SNAP!
     with the /F command-line parameter is equivalent to entering the program,
     pressing F6 at the System screen and entering a filename.


     Abbreviations

     In general, SNAP! is pretty good about recognizing valid X-Base
     abbreviations.  For example, it will properly detect that
          <tab>DO <tab> WHIL<tab>
     initiates a DO loop.  Version 3.00 also removed the earlier restriction on
     abbreviating INDEX ('SET INDE TO foo' is fine now).

     Also, if you use X-Base key words as variable names, SNAP! can sometimes
     become confused.  For example, if you use 'PROC' as a variable name within
     a procedure file and put the statement 'PROC = FOO' within the file, SNAP!
     will see the 'PROC' and think that it is initiating a new procedure.
     Common sense will ordinarily avoid this problem.  As always, it is a good
     idea not to use key words in a way other than that intended by the
     language, especially if you plan to compile the code; compilers tend to be
     more picky about this restriction than interpreters.


     Status Reports

     As SNAP! documents your programs, it updates a status screen that tells you
     how much progress it has made.  The screen shows the file that SNAP! is
     currently documenting and the number of lines in the file.  SNAP! makes two
     passes through each file--one to determine which files use or call which
     other files, and one for cross-referencing variables, formatting source
     code and preparing action diagrams.

     In addition, if you choose any option that modifies source code (headings,
     indentation, key word capitalization, compression or expansion, etc.), or
     if you choose to display the cross-reference report, SNAP! will display a
     more elaborate screen indicating how many programs (actually, programs,
     procedures, functions, etc.), databases, indexes, format files, report
     forms and variables it has found, along with the total number of program
     lines documented so far, and the amount of free memory available. This
     screen also shows the elapsed time since you began documentation.

     Note: some people have reported that the elapsed time is occasionally
     negative.  This is normal.  It means that your computer is actually running
     faster than light.  It is nothing to be concerned about unless you have an
     8087 chip, which sometimes overheats when moving backwards in time.

                                          10







     If SNAP! identifies any errors during its run, it will print a brief error
     message in a separate window in the upper right corner of the screen.  All
     error messages are also echoed to the ERROR.DOC file.


     Searching the Program Tree

     SNAP! assumes that you want to document not only the TopFile, but all
     programs it calls, all programs called by programs that Top calls, and so
     on.  In fact, SNAP! will search the program tree for all programs,
     databases, index files, report forms, format files, label forms, memory
     files, etc. as it prepares system documentation.  You never need to specify
     more than the top program file name.

     If you choose not to search the tree (you can make this choice on the Other
     Options Screen), only the specific file you enter will be documented.
     Thus, you can limit documentation to a particular file or a branch of the
     program tree by varying either the file you input as Top or the search tree
     parameter.

     Note that SNAP! does not track "SET DEFAULT TO x" statements, but always
     expects to see files with no drive designations on the default drive and in
     the source file subdirectory.


     dBASE Version?

     On the Other Options screen, SNAP! asks which version of X-Base you are
     using.  You should answer "4" if this is a dBASE IV or FoxPro system, or
     "3" if this is dBASE III or a dBASE III "compatible" -- specifically
     Clipper, FoxBASE+, or QuickSilver.  Answer "2" for dBASE II or FoxBASE
     (original, dBASE II variety).

     SNAP! needs this information since different versions of X-Base use
     different internal format for database and index files, as well as
     different key words.  SNAP! reads Clipper index files, and handles Clipper
     source code and databases without difficulty. If a specified dBASE III
     index file is not found, SNAP! automatically searches for the corresponding
     Clipper index file (with an NTX extension). SNAP! will also automatically
     detect FoxBASE and FoxPro index files (IDX or CDX extensions) and document
     them properly.

     Further, if you say that your system is a dBASE IV-type system, SNAP!
     assumes that report form files are in dBASE IV or FoxPro format.  If they
     are not, the system can hang when SNAP! bravely tries to read data that
     isn't there.


     Ignoring Drive Designations

     Sometimes you may want SNAP! to disregard explicit drive and path
     designations when searching for data files.  A choice on the Other Options

                                          11







     screen instructs SNAP! to drop any drive or path designations before
     attempting to find a file.  As an example, you may have written a backup
     routine to copy a database to B:BACKUP.DBF.  If you would like SNAP! not to
     try to find that file on the B: drive, choose the option to ignore drive
     designations.  This option has no effect on SNAP!'s search for program
     files.


     Printing SNAP! Documentation

     SNAP! often produces a lot of documentation--perhaps more than you will
     care to print.  It is not uncommon for SNAP! to produce several hundred
     pages of documentation for a X-Base system of modest size.  It could take
     days to print it all out on anything but a laser printer.

     You can print SNAP! documentation directly from SNAP!, with full control
     over page margins, printer codes and so forth.  Set up your printer options
     on the print options screen.  Hint: Press F2 while you are there and see if
     a set of default options for your printer already exists.

     By default, SNAP! sends its printed output to LPT1:.  This is usually where
     your printer is, but if it isn't, or if you would like to send the printed
     output to a file, use the -P command line switch, like this:
          SNAP -pCOM2:
     or
          SNAP -p\foo\bar\output.txt
     If you use the optional "NET" keyword:
          SNAP -pLPT2:(NET)
     you can tell SNAP! that your printer port (LPT2 in this example) is talking
     to a network printer and that SNAP! should be a little more forgiving about
     timeout warnings.

     Having said all that, I practically never print the documentation, but
     review it on the screen instead.  However, if you decide to print the SNAP!
     documentation files, you have several options.  First, you can simply copy
     them to the printer like this:
          COPY *.DOC PRN:

     A second option is to add the documentation files to the REPRINT.DOC file
     (you have to add them with an editor--SNAP! doesn't do it automatically)
     and use the "immediate print" capabilities of SNAP! (Press "F9--Print Now"
     from the Print Options Screen) to print them.

     Alternatively, you can use a program such as the LP program in Norton
     Utilities to print the files.  LP (it may be called LINEPRNT on your
     system) prints the files with nice headings and page numbers.

     If you have a laser printer, I recommend that you take a look at a
     Shareware program from Korenthal Associates called 4PRINT.  It prints four
     pages of text on each physical piece of paper and can greatly reduce the
     volume of printed SNAP! documentation.


                                          12







     I have gotten permission from Korenthal Associates to distribute 4PRINT on
     the SNAP! distribution disk.  If you have an HP laser printer, I encourage
     you to try 4PRINT.  If you use it and like it, please register it directly
     to Korenthal Associates at 230 West 13th Street, New York, New York 10011.
     Telephone: [phone].  It is also available on many bulletin board
     systems.  The registration fee for the full package with printed
     documentation is about $40.  Highly recommended.  When you register, please
     jot a note on the form or tell them on the phone that you heard about it
     through SNAP!.

     You can also run SNAP!, create documentation and formatted source code
     files, then later restart SNAP! and print the source code.  Whenever you
     choose to create a list of files used in the system (FILELIST.DOC), SNAP!
     also creates the REPRINT.DOC file that can be used to reprint all SNAP!
     source code and action diagram files.  Using the "F9--Print Now" function
     on the print options screen, you can tell SNAP! to print everything listed
     in REPRINT.DOC.  Should you decide to print any files in addition to source
     code and action diagrams, you can add their names to REPRINT.DOC.

     In addition to REPRINT.DOC, which holds the names of source code files,
     SNAP! creates DOCLIST.DOC, which holds the names of documentation files.
     Should you wish to, you can use the "F9--Print Now" option to print SNAP!
     documentation files.  Even so, I recommend 4PRINT instead (see above).


     Using a Mouse

     SNAP! is mouse friendly.  You can use the mouse to position the cursor in
     data entry fields, select function keys and navigate the help system.  To
     select one of the function keys with the mouse, point at the function key
     definition on the bottom of the screen.

     In general, pressing the left button is like pressing the enter key and
     pressing the right button is like pressing escape.  For example, pressing
     the right button from a data entry screen calls the main menu, just as if
     you had pressed escape.

     There are a couple of wrinkles to using the mouse inside the help system.
     Press the right mouse button to exit help.  If there is more than one
     screen of help, you can click on the arrow on the right side to scroll the
     page.  While help is active, you cannot move the mouse pointer outside the
     help window.











                                          13







                                    SNAP! Commands

     SNAP! supports several commands that you can insert in your source code
     files.  These commands will look like comments to X-Base systems, but will
     have a special meaning for SNAP!.  The commands allow you to define macros,
     insert imaginary program statements into your system, turn SNAP! features
     on and off for particular parts of your system, and so forth.

     Macros

     SNAP! has a limited ability to do macro substitutions.  To define a macro,
     place the following line in your source code:

          *# SNAPMACRO  source  target1 target2 . . .

     Alternatively, or in conjunction with this method, you can also define
     macro substitutions in a separate file.  Specify the /mfilename switch on
     the command line to tell SNAP! which file the substitution strings are in.
     For example, the following command will start SNAP! and read macro
     definitions from the file FOO.MAC:

          SNAP /mFOO.MAC

     If you do not specify a filename with the /m switch, SNAP! will try to find
     MACRO.SNP. You must use the full "*# SNAPMACRO" command verb on each line
     of the file.  Macro substitutions defined in source code files take
     precedence over those defined in a separate macro file.

     The /O switch on the SNAP! command line disables all macro processing, both
     from SNAPMACRO statements in source code and in a named macro file.

     Note that the SNAPMACRO statement begins with an asterisk and a pound sign.
     SNAP! uses this sequence of characters to designate a SNAP! command (see
     the /T command line switch for information on how to change these
     characters). 'Source' must be a single word, delimited by spaces or tabs.
     "Target" means the rest of the line.  Everything on the line--both source
     and target--will be converted to upper case.

     Note that the source string does not include the ampersand (&) symbol for
     the macro (e.g., use SOURCE instead of &SOURCE).  The rest of the line
     (minus leading and trailing blanks) will be used as a substitution string.
     The target can be a single word or several words.

     You cannot use && comments on a SNAPMACRO line since SNAP! will think they
     are part of the target.  If you want to document the purpose of the
     SNAPMACRO statement, put a comment on the line above it.

     The SNAPMACRO statement can appear anywhere, as long as SNAP! sees it
     before encountering the macro that you want to replace. If the target will
     have the same value throughout the system (e.g., FOO will always be
     replaced by BAR), it is a good idea to put all of the macros in one place,
     perhaps at the top of the TopFile or in a separate macro file.

                                          14







     If you would like SNAP! to use different macro values during documentation,
     you may want to place the SNAPMACRO statement immediately before the
     specific location of each macro substitution.  If you have multiple
     definitions for a single macro, only the last one SNAP! sees will be
     effective.  For example, if the following series of statements are in your
     program,

          *# SNAPMACRO s_ddndx  target1
          *# SNAPMACRO s_ddndx  target2
          *# SNAPMACRO s_ddndx  target3

     only 'target3' will be effective and will be substituted for each
     occurrence of &s_ddndx.  See also the discussion of SNAPCODE statements
     below for an alternative approach.

     SNAP! will try to remove macros that look like drive or path designations.
     For example, if the following statement is in one of your programs:

          USE &MPATH.DATABASE

     SNAP! will detect the macro and remove it before trying to find
     DATABASE.DBF.  One consequence of this limit is that you cannot use macros
     to refer to program files in different directories. All source code program
     files (programs, format files, memory files, etc.) must reside in the
     single program directory you specify in the System screen.  Databases and
     indexes can be in either the program or data directories you specify.

     SNAP! will not substitute the macro in the code itself, but will use the
     substitution value everywhere else.  For example, assume your program uses
     a database whose name is contained in a macro variable named 'dataname'.
     Assume further that you have included the following line in your code:

          *# SNAPMACRO dataname ABC.DBF

     If your code has this line in it:

          USE &dataname

     the source code will be unchanged after running SNAP!, but the program
     headings and all other SNAP! reports will show this program using the
     ABC.DBF database.

     See also the section below "Fake Program Statements--SNAPCODE" for other
     ideas on how to document macros.


     Indirect References

     In many circumstances, FoxPro and Clipper allow you to specify filenames
     and other strings as indirect references.  For example, the following code
     is valid in Clipper Summer 87:
        foo = 'FILENAME'

                                          15







        bar = '.TXT'
        SET PRINTER TO (foo+bar)
     This is equivalent to the statement:
        SET PRINTER TO filename.txt

     SNAP! partially supports indirect references.  When SNAP! sees one, it
     tries to apply macro substitution to the indirect reference.  Therefore,
     the following code will document properly:
        *# SNAPMACRO foo dbfname
        USE (foo)
     SNAP! will pick up the reference to the "dbfname" database.  However, more
     complicated indirect references will usually not be picked up correctly.
     For example, SNAP! will not be able to figure out what is going on in the
     following code:
        dirname = 'CLIPPER'
        USE ('C:\'+ALLTRIM(dirname)+'\filename')
     When SNAP! encounters such an indirect reference, it does not include it in
     the documentation.  This limitation only applies to FoxPro and Clipper
     systems, and only when you use indirect references.  You can use SNAPCODE
     (see below) to force this database to be documented.


     SNAPCODE--Fake Program Statements

     Sometimes you may want to enter fake program source code statements --
     statements that SNAP! treats as real but which do not actually interfere
     with your program when it executes.  A good example is a macro that calls
     one of a number of programs, depending on the value it has at run time
     (e.g., DO &program). The macro substitution discussed in the section above
     provides a way for you to specify one value for 'program'.  But suppose you
     wanted SNAP! to assume that 'program' had several values and to document
     each one in turn?  The *# SNAPCODE directive provides a way.

     The *# SNAPCODE directive causes SNAP! to treat any text on the line as if
     it were a program source code statement.  In the example above, you could
     enter the following lines where the macro was called:

          DO &program                    <---- in original program *# SNAPCODE
          DO foo
          *# SNAPCODE DO bar
          *# SNAPCODE DO brlfq

     SNAP! acts as if these were perfectly straightforward calls to 'foo', 'bar'
     and 'brlfq', and documents them accordingly.  dBASE and related systems
     ignore the statements.

     Note that SNAP! does not know that these SNAPCODE statements have anything
     to do with the DO statement above.  SNAP! does not associate 'foo' with
     'program'.  The next time SNAP! sees 'DO &program' it will not assume that
     'program' has the value 'foo'. If you want SNAP! to associate values with
     macros, use the SNAPMACRO directive.


                                          16







     As a side benefit, SNAPCODE statements help document your code by
     specifying the permissible values that particular macros can take.


     Multiple Program and Data Directories

     SNAP! prompts you for a program and a data directory on the system screen,
     but you can define additional directories with special directives, as
     follows:
          *# SNAP PRGPATH \foo\bar1
          *# SNAP PRGPATH \foo\bar2
               ... and so forth
     and
          *# SNAP DATAPATH \foo\bar3

     When SNAP! looks for a file, it first searches the current directory, then
     all the program directories (for a program-type file) or the data
     directories (for a data-type file).

     Program-type files include: programs, procedure files, format files, report
     forms, label forms, FoxPro 2.0 files (queries, screens and menu files),
     memory files and binary files.

     Data-type files include databases, indexes, and multiple indexes.


     Program Narratives

     An important part of a well-documented system is a narrative explanation of
     the purpose of each program module.  Unfortunately, SNAP! can't figure this
     out on its on.  However, it does allow you to describe your programs, and
     it provides a way for your descriptions to be echoed to the HEADINGS.DOC
     file.  Any comments that start with "*)" will be interpreted as program
     narratives and will be sent to HEADINGS.DOC.  Naturally, these comments
     will also be left alone in the source code.  Normally you will want to put
     these narratives immediately below the SNAP! headings, but SNAP! will
     recognize them wherever they are.


     Other SNAP! Directives

     Other SNAP! commands, or directives, allow you to turn cross- referencing
     and program formatting on or off for particular programs.  For example, you
     may have "boilerplate" code that you have thoroughly debugged and formatted
     which you insert into many other systems.  It would be unnecessarily
     time-consuming to reformat this code every time you ran SNAP!.  SNAP!
     provides other commands to temporarily suspend cross-referencing and
     formatting-- XREF, FORMAT, INDENT, CAPITAL, and EXPAND.  Each of these
     commands accepts three settings--ON, OFF and SUSPEND.  The ON and OFF
     commands are effective until SNAP! sees another directive, while SUSPEND is
     in effect only until the end of the current program or procedure.  For
     example, if you insert this line in your code:

                                          17







          *# SNAP XREF OFF
     no tokens will be cross-referenced until this line is encountered:
          *# SNAP XREF ON
     On the other hand,
          *# SNAP XREF SUSPEND
     suspends cross-referencing only for the current file.  It starts up again
     when the next program or procedure is documented.

     I suspend cross-referencing for commonly-used subroutines in my code.  For
     example, since Clipper does not have a BROWSE command, I often include a
     public-domain BROWSE program in my systems. This is a standalone module
     that really has nothing to do with the rest of my system, and I don't want
     its variables cluttering up my cross-reference report.  So, I say:
          *# SNAP XREF SUSPEND
     at the top of the file and SNAP! leaves it alone.

     SNAP FORMAT works in the same way.  If format is off, no indenting or
     capitalization will be done.  When SNAP! sees a SNAP FORMAT statement, it
     affects the internal codes that determine whether indenting, capitalization
     and key word expansion (or contraction) take place.  The three commands
     (INDENT, CAPITAL and EXPAND) turn specific features on or off.  Thus, the
     following sequence suspends indenting and capitalization, but enables key
     word expansion:
          *# SNAP FORMAT SUSPEND
          *# SNAP CAPITAL ON
     Thus, FORMAT is a shorthand way of referring to CAPITAL, INDENT and EXPAND
     all at once.

     If *# is an inconvenient sequence for you (e.g, it may cause confusion with
     the British pound sign), you can change it with the /T switch on the
     command line.  For example, if you invoke SNAP! with the switch "/T*$",
     SNAP! will use *$ to designate SNAPMACRO, SNAPCODE and other SNAP!
     directives.  You must start this sequence with an asterisk (so that dBASE
     knows it is a comment) and it cannot be more than three characters long.



















                                          18







                            Source Code Formatting Options


     File Headings

     One of the most useful SNAP! features is a heading written to each file in
     the system.  Each heading indicates:

          Program name
          System name
          Copyright notice
          Author
          Procedures defined within this file
          Which programs this program calls
          Which programs call this program
          Databases, index files, report forms, format files, label forms,
          memory files, etc. used by this program
          Date and time documented.

     A sample heading is included in the Appendix.   The sample heading
     indicates that TODOINP.PRG is called by TODOMENU, calls TIME and TESTDATE,
     uses a file whose name is contained in S_TDFILE with index TODO (macro
     substitution was not used for this example), and also uses the TODOINP
     format file.  The heading also indicates the system name, author, copyright
     and date documented.  You may want to add more information to the header,
     such as a brief narrative description of the program's purpose.

     If you choose to write headings on your source code files (or if you choose
     any other option that modifies the source code file), it is a good idea to
     send the output files to a different directory than the input files so that
     your original source code remains unchanged.

     If you choose to send output files to the input directory, your original
     source code file will be renamed with a .BAK extension. If you use
     extensions to distinguish between program files, some of your original
     source code files could be destroyed.  For example, if your system uses the
     following program file names:

          SYSTEM.INP
          SYSTEM.EDT
          SYSTEM.RPT
          SYSTEM.DEL

     and so on, the output files containing the headings will retain these
     names.  Each of the input files, however, will have been renamed to a file
     called SYSTEM.BAK, and only the last one will still exist when SNAP!
     completes.  Therefore, you should always send output files to a separate
     subdirectory if you use this naming convention.

     As always, you should make regular backups, and you should be especially
     careful to make a full backup of all your files before running SNAP!.


                                          19







     By default, SNAP! leaves the date and time of last update unchanged for
     each of your files.  You can instruct SNAP! to update the date and time
     last changed on the source code format screen.  The headings written to
     each program file show the date and time SNAP! was run.


     Indentation

     SNAP! can also help format your source code to make it easier to read.
     SNAP! can recognize dBASE control structures and indent the program
     statements underneath them.  By default, indentation is three spaces.  If
     you choose tabs, however, should you choose to use SNAP!'s source code
     printing routines you can select the number of spaces to be inserted for
     each tab as the code prints.

     However, if you would like to use spaces rather than tab characters for
     indenting, you can select this option from the Format options screen.  For
     example, you can instruct SNAP! to use three spaces for each indentation
     level.  This option has no effect if you do not choose to indent source
     code.  It is different from the option in the source code printing facility
     that also allows you to expand tabs.  If you choose to use spaces to indent
     your source code files, the source code will not contain tabs, so the
     source code printing tab-expansion feature will have no effect.

     If you choose to indent source code or create action diagrams, SNAP! will
     also scan your code for mismatched control structure terminators.  For
     example, if your code has the following sequence:

          DO WHILE T      statements
          .
          .
          .
          IF X = Y
          .
          .
          ENDIF
          ENDIF      <---- incorrect

     SNAP! will detect that the final statement should have been an ENDDO
     instead of an ENDIF and will display an appropriate error message.  SNAP!
     will accept 'END' as a valid abbreviation of ENDDO, ENDIF or ENDCASE.

     SNAP! does not track control structures across program or procedure
     boundaries.  Normally, this is not a problem since you cannot start a DO
     WHILE loop in one program and finish it in another.  BREAK statements,
     however, can exit from a BEGIN/END SEQUENCE control structure that is
     defined in another program. If SNAP! encounters a BREAK statement but
     cannot find the BEGIN/END SEQUENCE structure, it reports an error.  Just
     ignore it if you know that the BREAK is valid.




                                          20







     The format options screen allows you to add an extra level of indenting
     underneath procedures and functions.  By default, SNAP! indents procedures
     and functions like this:
          PROCEDURE something
          foo = bar
          ? 'Hello, sailor'
          RETURN

     If you choose to indent procedures and functions, your source will appear
     like this:
          PROCEDURE something
               foo = bar
               ? 'Hello, sailor'
          RETURN

     Most people indent CASE statements in the following way, as God intended:

          DO CASE
          CASE foo = bar
          CASE xyzzy = plugh
          ENDCASE

     Certain stubborn users, however, insist on indenting CASE statements like
     this:

          DO CASE
               CASE foo = bar
               CASE xyzzy = plugh
          ENDCASE

     If you invoke SNAP! with the -A command line switch, you too can use this
     wretched technique.


     Capitalization

     SNAP! will also capitalize dBASE key words found in your source code.  Key
     words are stored in a file called DBxWORDS.SNP where x is a 2, 3 or 4
     depending on the version of dBASE you are using (you can also specify
     another file).  SNAP! does not attempt to parse code statements to
     determine how a word is used, so if you use key words as variable or field
     names, they will also be capitalized.  Should you wish not to capitalize a
     particular key word, you can either delete it from the DBxWORDS.SNP file,
     or "comment it out" by putting an asterisk before it in the file (e.g.,
     RELEASE becomes *RELEASE).

     The preceding paragraph assumes you prefer "standard" capitalization--key
     words are capitalized, functions have an initial capital letter, and
     everything else is in lower case.  If not, you can change it on the Format
     screen.  You can select upper case, lower case, initial caps, or none
     (leave it alone) for both tokens and for key words.  Thus, if you were so


                                          21







     inclined, you could capitalize tokens (variables, etc.) and lowercase key
     words.


     Key Word Expansion and Compression

     SNAP! will allow you to expand abbreviated key words to their full length,
     or to abbreviate the key words to four characters. Compilers don't care
     about any of this, but the dBASE interpreter runs programs slightly,
     usually very slightly, faster if the key words are abbreviated to their
     first four characters.  An option on the Format screen controls how
     expansion or compression is done.  The default is no expansion or
     compression--SNAP! leaves your code alone.  However, you can select
     expansion, or compression to any number of characters between 4 and 9.

     Please be careful with this option, especially if you are not very careful
     about how you name variables.  The only thing SNAP! knows about key words
     are that they are in the key words file. If one of your variables is a key
     word (or a valid abbreviation of a key word), SNAP! will cheerfully expand
     or contract it along with everything else.  SNAP! cannot tell how whether a
     particular word is being used as a command or as a variable.  Normally,
     this will not be a big problem--if you named a variable "title" and
     compressed key words, it will now be called "titl".  Problems could arise,
     however, if two variables are valid abbreviations of the same key word
     (e.g., "other" and "otherw", both of which are valid abbreviations of
     OTHERWISE).  If you compress key words and have such variable names, both
     variables will be compressed to OTHE, and there is no way to separate them
     again.  Also, if you are using a dialect of X-Base that supports
     user-defined functions (UDFs), and if one of the UDFs has the same name as
     a key word (Tom Rettig's BLANK() function, for example), the UDF name will
     be compressed (assuming the UDF name was in the key words file). If you
     compress keywords in this case, nothing desirable will happen.

     Because of the irrevocable changes that this option can make, SNAP! will
     not allow you to exercise it if the source and output directories are the
     same.  In other words, SNAP! will refuse to overwrite your original source
     code files if you select this option.  Big brother is looking out for you.

     If you use the compression option, please run the compressed code and
     ensure that it works before you delete the backups that SNAP! made.

     Key words that are identified in the key words file as functions (they have
     () after their name--see below) are never affected by key word compression
     or expansion.


     Suppressing Blank Lines and Comments

     You can suppress blank lines and/or comments from the output files by
     selecting the appropriate options on the Format screen. I do not recommend
     this, but it does make interpreted X-Base applications run slightly faster.
     Please be doubly sure to make backups before doing this.  SNAP!'s default

                                          22







     options are to leave both blank lines and comments in the output file, so
     you have to take special action yourself before they will be dropped.

     Clipper "/* */" and "//" comments are not removed even if you elect to
     eliminate comments.

     As with key word expansion and compression, you cannot select this option
     if the source and output subdirectories are the same.

     If you know how to design an effective counterpart to this feature--how to
     put the comments back in--please contact me about a potentially lucrative
     commercial venture.


     Key Words File

     Capitalization, cross-referencing and key word expansion and compression
     are controlled by the words in the key words file. The key word file should
     contain one key word per line. Capitalization and order do not matter,
     except that if two identical key words have different flags (see below),
     the last one takes precedence.

     By inserting the correct characters in the key word file, you can cause
     certain key words or variables to be handled differently than normal.  The
     following characters have a special meaning in the key word file when
     inserted immediately before a word:

          *    Comments out the word.  SNAP! acts as if it were not in the key
               word file at all.

          !    Capitalize, but do no cross-reference even when the option to
               cross-reference key words is in effect.  You may want to use this
               character for often-used but uninteresting key words such as TO
               or, perhaps, SAY.

          @    Capitalize and always cross-reference this word, even when the
               option to cross-reference key words is not in effect.  You might
               want to use this for especially important key words such REPLACE,
               SAVE, or QUIT.

          %    Neither capitalize nor cross-reference, regardless of whether the
               options to capitalize or cross-reference key words are in effect.
               You may want to use this character for variables that you use
               frequently, but that you are not interested in
               cross-referencing--perhaps "i", "choice", "action", or "lineno".
               This will keep them from cluttering up the cross-reference
               report.  Such words are not affected by key word expansion or
               contraction.

          ()   If the *last* two characters in a key word are (), the key word
               will ordinarily have an initial capital letter in the formatted
               output.  The DB3WORDS.SNP file that comes with SNAP! uses this

                                          23







               notation to designate the Tom Rettig key words (Tom Rettig is the
               author of a popular set of functions for dBASE III and Clipper)
               and the keywords in the PROCLIP3 library.  Functions are never
               affected by key word expansion or contraction.

     The following examples illustrate how to use these special characters:

          *note
          !SAY
          @REPLACE
          %CHOICE
          SOME_FUNCTION()

     There are two ways to tell SNAP! about key words.  First, the Format screen
     allows you to specify the main key words file, which will usually be
     DB4WORDS.SNP for FoxPro or dBASE IV systems, DB3WORDS.SNP for Clipper,
     dBASE III and FoxBASE+, and DB2WORDS.SNP for any wretches still using dBASE
     II.  In addition, SNAP! will look for a file called PERSONAL.KEY in the
     SNAP! subdirectory (the subdirectory where you put SNAP!--it doesn't
     actually have to be named "SNAP!").  Anything found in PERSONAL.KEY will be
     treated just as if it were in, say, DB4WORDS.SNP.  Therefore, you can
     customize your key words list without messing up the factory-installed
     DB4WORDS.SNP file.

     SNAP! is distributed with key words files for a variety of third-party
     function libraries.  Naturally, different programmers will use different
     libraries.  If you use one of the supported libraries, just include its key
     words into the main SNAP! key words file (e.g., DB4WORDS.SNP) or into your
     PERSONAL.KEY file.  The best way to add a library's key words is to put "*#
     INCLUDE" statements like this in your PERSONAL.KEY file or into
     DB4WORDS.SNP:
        *# INCLUDE rettig.key
        *# INCLUDE proclip.key
     SNAP! will then recognize all the key words in RETTIG.KEY.  These "*#
     INCLUDE statements" can be nested, but they have to be in either the main
     key words file or in PERSONAL.KEY.  A "*# INCLUDE" statement in a source
     code file is ignored.  In addition to using "*# INCLUDE" statements, you
     can use a word processor or program editor to move the words into
     PERSONAL.KEY or DB4WORDS.SNP.

     "Support" for third-party libraries is really just a list of key words.
     You can easily add key words from any other library that I didn't include--
     SNAP! itself doesn't have to be modified.

     SNAP! provides enough space for a maximum of 1,500 key words.  This is far
     more than is required for all dialects of X-Base put together, but is not
     enough for all of the third-party libraries also.  Therefore, you should
     just update the main key words file for the libraries you actually use.
     Any key words past the limit will be ignored.

     SNAP! does not try to detect duplicate key words.  They don't cause any
     harm, but they all count against the limit.  If you have duplicate key

                                          24







     words with different control characters (see above), the control character
     set that will be used by SNAP! is deterministic but unpredictable.



















































                                          25







                                 Reports and Outputs

     SNAP! can produce any combination of several reports.  Each report is
     optional and can be selected or suppressed on the Options Screen. However,
     some reports (e.g. Database summary, Index summary) require you to search
     the tree rather than document a single program.

     Normally, SNAP! tells you that it is producing a particular report, but
     does not display the report on the screen.  However, each report other than
     a file heading, may be displayed on the screen as it is echoed to a file.
     You can enable screen echoing by invoking SNAP! with the /S command line
     parameter.  I like to see the reports being generated but some people
     prefer to silence the screen to improve SNAP!'s speed.  Note that the /S
     switch only affects the screen display of reports and has no effect on the
     status screens that are displayed as SNAP! scans source code files.

     The program contains default filenames (e.g., XREF.DOC for the
     cross-reference report), but you can change them if you wish.


     Controlling the Printer

     SNAP! allows you to specify a number of parameters for controlling your
     printer.  These parameters include margins, setup strings, and so forth.
     In addition to entering them directly, you can also press F2 and select
     some standard printer configurations from a scrollable list.  These printer
     definitions are stored in the SNAPPRT.SNP file, an ASCII file which you can
     edit yourself to add more printer definitions.  SNAP! supports up to 10
     printer definitions.


     System Summary

     This report shows the following information:
          System name
          Author
          Current date and time
          Lines of code
          Number of programs, procedures, procedure files, indexes, and so forth

          Names of databases, indexes, report forms, label forms and memory
          files

     The system summary would ordinarily be the first page in the documentation.
     It, together with the tree diagram, provides a basic overview of the entire
     system.  See Appendix A for an example.

     Tree Structure Diagram

     If you choose the default option of documenting all programs in the tree,
     SNAP! will produce a chart showing which programs call which other programs
     and which programs use which databases.  The tree diagram, like other SNAP!

                                          26







     reports, appears on the screen and is echoed to a file (default name of
     TREE.DOC).

     Any procedures or databases in the tree will be designated like this:
          Gee (procedure in procedure.file)
          Whiz (database ALIAS baz)

     SNAP! by default includes programs, procedures, functions, format files and
     databases in the tree. The Tree Screen includes options that allow you to
     put indexes, report forms, label forms and memory files in the tree also,
     or to suppress any of the default file types except program files.

     Note that the databases (and other non-program files) are shown underneath
     the programs that actually call them.  If a database is opened in one
     program and remains open in another program, SNAP! will show the database
     as called only by the first program file.

     SNAP! has some code to detect certain types of recursion and prevent the
     tree from marching off the right side of the page and eventually off the
     end of the world.  SNAP! catches programs that call themselves and programs
     that call another program that calls the original program again.  If the
     recursion is more subtle than that, SNAP! will eventually give up when
     recursion reaches 25 levels.  You will have become bored watching the
     display by that point.

     SNAP! detects calls to other programs, procedures and functions when they
     are in one of the following formats:
          DO something
          SET KEY 300 TO something
          ON KEY 300 DO something
          ON KEY=300 DO something
          ON KEY DO something
          ON KEY LABEL keylabel DO something
          ON ESCAPE [or ERROR] DO something
          ON READERROR DO something
          ON SELECTION PAD ... DO something
          ON SELECTION POPUP ... DO something
          ON PAGE x AT LINE y DO something
          foo = something()    <---SNAP! detects other UDF calls also
          CHAIN something
          SWITCH something
          SET FORMAT TO something

     Further, SNAP! detects calls to user defined functions in certain Clipper
     functions--MEMOEDIT, DBEDIT and ACHOICE.

     SNAP! searches through procedure files to generate a complete list of
     procedures and functions.  It identifies procedure files in the following
     ways:
          EXTERNAL procfile
          SET PROCEDURE TO procfile
          SET UDF TO procfile

                                          27







     Also, SNAP! will detect any procedures that are tacked on to the bottom of
     a PRG file, a coding style that Clipper allows.

     There are other "things" that sometimes act like programs.  For example,
     dBASE IV creates an FRG file whenever you use its report writer.  In
     reality, this file is a procedure file that contains code to produce the
     report.  SNAP! detects that an FRG file exists and shows it begin called
     from the program that initiates the report--the one that contains the
     REPORT FORM ... TO ... statement.  Similarly, label LBG files are also
     detected and documented.

     The tree report is illustrated in the Appendix.


     File List

     SNAP! can write a simple list of all files used in the system, including
     programs, databases, index files, and so on.  This report can be useful for
     identifying which files in a directory are associated with an application.
     The file list can also be fed into the source code printing routines at a
     later point, so that the program files can be printed without going through
     a time-consuming complete documentation run again.

     Database Summary

     The database summary report contains two parts: 1) the database structure
     for each database in the system and a list of programs which use it; and 2)
     a listing of each data field in the system and the databases that contain
     it.

     SNAP! tries to figure out which indexes, report forms and label forms are
     associated with each database.  It tracks the following statements:
          USE dbfname
          SELECT A (or B, C, etc. up through J)
          SELECT aliasname
          CLOSE DATABASES
          CLOSE ALL
          USE
     SNAP! knows how to account for macros in each of these constructions,
     assuming you have defined the macro.  For example, USE &temp will be
     interpreted to mean USE abcfile if you have previously defined &temp to
     mean abcfile (see section on SNAPMACRO statements for more details).

     SNAP! is reasonably good, but certainly not perfect, at figuring out which
     database is active at a particular spot in the code. There are, however,
     some limitations you should be aware of. First, SNAP! does not track
     databases or areas across program files or procedures.  Whenever SNAP!
     begins documenting a file, it assumes that no databases are in use and that
     area A is active.  Also, SNAP! does not try to interpret conditional
     structures.  For example, consider the following code:
          IF .T.
               USE foo

                                          28







          ELSE
               USE bar
          ENDIF

     SNAP! looks at this code one line at a time.  The last USE statement it
     sees is 'USE bar'.  That statement will never actually be executed (because
     of the IF test), but SNAP! doesn't know that.  You may need to use SNAPCODE
     statements to help SNAP! figure out what is happening in cases such as this
     one.

     SNAP! identifies databases in these ways:

          1)   USE statements, but only those followed by a database name;
          2)   COPY TO statements, including COPY TO ... SDF.  If the command
               copies to an SDF file that does not have an explicit extension,
               SNAP! supplies .TXT. Otherwise SNAP! assumes databases to have
               .DBF extensions.
          3)   DELETE FILE xxx.DBF
          4)   CREATE foo FROM bar    (SNAP! picks up both foo and bar)
          5)   CREATE foo
          6)   COPY FILE foo.dbf TO bar.dbf
          7)   COPY STRUCTURE [EXTENDED] TO foo
          8)   SORT ON keyname TO foo

     A statement that tests for the existence of a database (e.g. IF
     FILE("xyz")) will not by itself be identified as a database reference.
     Currently, SNAP! imposes an overall limit of 1,024 fields in the entire
     system.  If you exceed that number, SNAP! complains and does not include
     the excess fields in the database summary.

     A sample database summary report is included in appendix A.


     Index File Summary

     The index file summary lists each index file referenced in the system and
     attempts to show the fields it is indexed on and the files that use it.  It
     also shows multiple index files and their tags in a separate section of the
     report.

     SNAP! first checks for an index file with the default extension you
     specified on the "Other Options" screen. If it cannot find a file with that
     extension, it tries to find one with an extension of NDX (the usual
     extension of dBASE II, dBASE III index files).  If it cannot find this
     file, it tries to find the same file name with an NTX extension (the usual
     extension of Clipper index files).  Failing that, it tries FoxBASE+/FoxPro
     IDX extensions.  If SNAP! cannot find one of those either, it gives up and
     reports that the NDX file could not be found.  If, however, it could find
     the Clipper or FoxBASE+/FoxPro file, it documents it appropriately.




                                          29







     SNAP! also shows the database associated with each index, if it could
     figure it out.  The database summary section of this documentation
     discusses the assumptions that SNAP! makes about which database is active.

     SNAP! identifies indexes in five ways:

          1)   INDEX ON xyz TO indexfile
          2)   USE xyz INDEX indexfile1,indexfile2,indexfile3 ...
          3)   SET INDEX TO indexfile1,indexfile2,indexfile3 ...
          4)   DELETE FILE xyz.NDX
          5)   COPY FILE foo.ndx TO bar.ndx

     In cases 2 and 3, each index file will be separately identified and
     documented.

     A statement that tests for the existence of an index (e.g. IF
     FILE("xyz.NDX")) will not by itself be identified as an index reference.

     SNAP! identifies multiple index files (MDX files) in the following ways:
          1)   INDEX ON bar TAG foo OF xyz
          2)   USE xyz  (when XYZ.MDX exists)
          3)   SET INDEX TO xyz
          4)   COPY TAG foo OF xyz TO ndxname

     A sample index file summary in shown in the Appendix.


     Format File Summary

     SNAP! also produces a report showing each format file used in the system
     and the programs that call it.  A sample report is in the Appendix.

     SNAP! identifies format files in two ways:

          1) SET FORMAT TO xyz
          2) DELETE FILE xyz.FMT

     In case 1, if this is a dBASE II system, SET FORMAT TO SCREEN and SET
     FORMAT TO PRINT are not flagged as references to format files.

     A statement that tests for the existence of an format (e.g. IF
     FILE("xyz.FMT")) will not by itself be identified as an format reference.


     Report Form Summary

     SNAP! also produces a report showing each report form used in the system,
     the report parameters, and the programs that call it. For dBASE III,
     FoxBASE+ and Clipper systems, SNAP! shows a mock- up of each report and the
     expressions that go into each column. It also indicates which database is
     associated with the report form.


                                          30







     Documentation for dBASE IV and FoxPro report formats is simpler and does
     not include a mock-up of the report.  Documentation for both dBASE IV and
     FoxPro shows the fields or expressions that comprise the detail records.
     Since both systems contain very sophisticated and elaborate report
     generators, it is not practical to summarize how the report looks, so SNAP!
     focuses on its contents.  You may wish to take a screen print of the report
     generator as additional documentation.  Also, apart from the documentation
     that SNAP! automatically produces, you may wish to retain a sample report
     printout.  Such a sample is probably a better indication of what the report
     does than the SNAP! documentation.

     A sample dBASE III report is in the Appendix.

     SNAP! identifies report forms in two ways:

          1)   REPORT FORM xyz ...
          2)   DELETE FILE xyz.FRM

     A statement that tests for the existence of an form (e.g. IF
     FILE("xyz.FRM")) will not by itself be identified as an report form
     reference.


     Label Form Summary

     The label form summary shows the parameters of each label form in the
     system.  It also indicates which database is associated with each label
     form.  A sample report is in the Appendix.


     Procedure File Summary

     SNAP! allows you to prepare a summary of files that contain procedures (see
     example in appendix A).  This summary shows the procedures in each
     procedure file and the programs and procedures that each one calls and is
     called by.  The report shows each procedure and function in the TopFile
     system.  SNAP! also reports the parameters expected by any procedures or
     functions that accept parameters.  Note that this report covers both
     procedure files and ordinary program files that also contain procedures (as
     Clipper allows).


     Other Summary Reports

     SNAP! also produces summary reports for the following additional file
     types:
          1) Memory files
          2) Binary (LOAD/CALL) files
          3) Other files

     Other files are generally text files that are specified in the following
     ways:

                                          31







          1) SET ALTERNATE TO xyz
          2) SET PRINTER TO xyz
          3) COPY MEMO to xyz
          4) APPEND MEMO FROM xyz
          5) COPY FILE xyz TO abc   <-- when SNAP! doesn't recognize the file
                                        extension
          6) TYPE xyz

     The other files summary report lists these files and shows which programs
     or procedures made a reference to the file.  I don't guarantee that the
     report will pick up every possible "other" file, but it seems to catch all
     of them in the sample code I use to test it.


     Variable Cross-Reference Report

     Another useful report available through SNAP! is a variable cross-reference
     listing, showing line numbers for each program that references a particular
     variable.  'Variable' in this context includes field names, file names and
     anything else that isn't a key word, numeric constant, punctuation mark or
     quoted string.

     If you elect to display the variable cross-reference report (by responding
     'Y' to the question on the options menu), you can view the Cross-reference
     Options Screen.  The Cross-reference Options Screen allows you to select
     the type of "things" that will included on the cross-reference report.  You
     will have the option to include only PUBLIC variables (this option has no
     meaning if this is a dBASE II system).  You also get the following choices:

          Include other variables and tokens
          Include key words
          Include numeric constants

     Your responses to these prompts (and your use of special characters in the
     key words file--see below) determine which words will appear on the
     cross-reference report.

     The cross-reference report adds certain codes to the end of a line number
     reference when the reference is particularly interesting.  SNAP! looks for
     the following statements to tell if a variable or field name (assume its
     name is 'abc') is interesting:

          Reference Type                                   Report Flag
          abc = 4                                                 *
          STORE 4 TO abc                                          *
          WAIT to abc                                             *
          @ 1,1 GET abc PICTURE "blah, blah"                      G
          ACCEPT "something" TO abc                               G
          INPUT abc                                               G
          REPLACE abc WITH something                              R
          RELEASE abc                                             x
          PUBLIC abc                                              P

                                          32







          PRIVATE abc                                             V
          LOCAL abc                                               V
          STATIC abc                                              V
          &abc                                                    &
          DECLARE abc[100]                                        A
          DIMENSION abc(100,200)                                  A
          USE abc [INDEX ...] [ALIAS ...]                         U
          DO foo WITH @abc                                        @

     As the following sample excerpt from the cross reference report
     illustrates, you can tell at a glance what is happening to the variables
     you are using:

     ABC
          TODO.PRG         30P   41    42    43G   44    45*   46G
          TDINPUT.PRG     123V  234*  235   237
          SETFILT.PRG      16    24    28    32
          TDEDIT.PRG      107*  133   134   135   136   138x

     This report shows that variable 'abc' was used in four programs (TODO,
     TDINPUT, SETFILT and TDEDIT).  Within TODO, it was declared a PUBLIC
     variable on line 30; referenced but not changed on lines 41, 42 and 44;
     used in a GET statement on lines 43 and 46; modified in line 45; and
     released on line 72.  TDINPUT declared it to be PRIVATE (line 123),
     assigned it a value in line 234, then referred to it in lines 235 and 237.

     A legend to explain all these flags is printed at the top of each
     cross-reference report, so you do not need to remember what they all mean.

     SNAP! will not flag a 'RELEASE ALL' statement as a reference, nor will it
     figure out that a 'RESTORE FROM xyz.mem' may overwrite other variables.
     Neither of these statements will generate a cross-reference listing for any
     variables (though xyz.mem will be referenced).  Of course, you can have
     SNAP! cross-reference the RELEASE and RESTORE statements themselves.

     By default, references to a database field prefaced by the alias (e.g.,
     foo->bar) will be shown as one token in the cross reference file.  If you
     do not like this convention, the /C command line option turns it off, so
     that foo and bar will be referenced separately.

     At the bottom of the report, SNAP! produces a list of public variables, a
     list of macros and a list of arrays.  The macro list is subdivided into
     macros that you defined to SNAP! and those you didn't.  If you defined a
     macro, its definition is also shown.

     A new option introduced in SNAP! 5.0 is the local cross reference report,
     so called because it is "local" to a particular program or procedure file--
     all variables and references in that a file are stored together in the
     local cross reference report, and are not merged together with all such
     references throughout the program system as is usual.  This report is
     generally less useful than the default global cross reference (which is
     what you are used to if you've been using SNAP! in the past).  It does have

                                          33







     the singular benefit of using almost no memory, however, so you can
     document much larger systems if you elect to create a local cross
     reference.  The local cross reference report and the global cross reference
     are mutually exclusive.  You chose to create a local cross reference on the
     cross reference options screen.

     Another technique for documenting a large system is to split your system
     into several smaller parts and document them separately.  Should you choose
     to do so, you might want to explore a program written by Charles S.
     Galloway called SNAP! XRef Merger that merges multiple cross references
     reports into a single consolidated report.  It is a nice piece of work.  It
     is available directly from Mr. Galloway at 3211 Burns Place, Raleigh, NC
     27609.  He will send you a copy if you send him a stamped mailer and a
     formatted diskette.

     The cross-reference report interacts closely with the key word file.
     Specifically, the key word file is how SNAP! can tell what is a key word
     and what is not.  Additionally, by inserting the correct characters in the
     key word file, you can cause certain key words or variables to be handled
     differently than usual.  The following characters have a special meaning in
     the key word file when inserted immediately before a word:

          *    Comments out the word.  SNAP! acts as if it were not in the key
               word file at all.

          !    Capitalize, but do no cross-reference even when the option to
               cross-reference key words is in effect.  You may want to use this
               character for often-used but uninteresting key words such as TO
               or, perhaps, SAY.

          @    Capitalize and always cross-reference this word, even when the
               option to cross-reference key words is not in effect.  You might
               want to use this for especially important key words such REPLACE,
               SAVE, or QUIT.

          %    Neither capitalize nor cross-reference, regardless of whether the
               options to capitalize or cross-reference key words are in effect.
               You may want to use this character to designate variables that
               you use frequently, but that you are not interested in
               cross-referencing--perhaps "i", "choice", "action", or "lineno".

          ()   If the *last* two characters in a key word are (), the key word
               will ordinarily have an initial capital letter in the formatted
               output.  The DB3WORDS.SNP file that comes with SNAP! uses this
               notation to designate the Tom Rettig key words (Tom Rettig is the
               author of a popular set of functions for dBASE III and Clipper).

     The following examples illustrate how to use these special characters:

          *note      --  This word will be ignored.
          !SAY       --  Capitalize, but do not cross-reference, SAY.
          @REPLACE   --  Include REPLACE in the cross-reference report.

                                          34







          %CHOICE    --  Do not capitalize or cross-reference this word.
          Alltrim()  --  This word is a function.  The first letter will be
                         capitalized.

     If this is a dBASE III or dBASE IV system, SNAP! allows you to restrict the
     cross-referencing to PUBLIC variables.  If you select this option, SNAP!
     only puts public variables on the report.  However, SNAP! does not look for
     PRIVATE statements that redefine the variable, so if a variable is declared
     PUBLIC anywhere in the system, SNAP! documents all subsequent occurrences
     of it.  Note that SNAP! does not "backtrack" to see if the variable was
     referenced before it was defined as PUBLIC.

     I have done my best to identify key words used in dBASE, FoxBASE, FoxPro
     and Clipper, but I may have missed some.  Fortunately, the DBxWORDS.SNP
     file is a standard ASCII file that you can edit with most any word
     processor. So, if I have omitted one of your favorite key words, it is a
     simple matter to add it to the file. Function names from other third-party
     libraries are also included, but you may also want to add function names
     from other development tools.

     A sample cross-reference report is included in the Appendix.


     LNK and MAKE files

     These options will be useful only to developers of Clipper-compiled
     applications.  If you are using interpretive dBASE III, dBASE IV or FoxPro
     you can ignore this section.

     Link Files.  SNAP! can produce a link file for PLINK86 (which comes with
     Clipper), TLINK (part of the Borland Turbo C package), and the Microsoft
     LINK utility.  If you are a serious Clipper programmer, the TLINK linker
     justifies the cost of the Turbo C package (less than $100)--it is that
     fast.  I have seen some informal benchmarks that show it linking
     applications as much as eight times faster than PLINK86.

     PLINK86 will accept "commands" from a LNK file.  This file typically
     contains a series of commands for the linker, telling the linker such
     things as which libraries to search and in what order.  SNAP! will produce
     a LNK file if you select the appropriate option.  This LNK file will
     contain a list of all the files in your system.

     If you have a file named LINK.SNP in your source directory, SNAP! will put
     it at the top of the LNK file.  For example, you might put a list of
     libraries in this file.  You can also use a name other than 'LINK.SNP' by
     specifying /Lfilename on the command line.

     Make Files.  SNAP! can produce the files for the Clipper MAKE utility
     (Summer 87 version only) and for the Shareware NDMAKE program.

     MAKE is a standard UNIX (tm) utility, versions of which are now also
     available for MS-DOS.  MAKE allows you to define which files "depend" on

                                          35







     other files and only compile files that have changed. For example, in a
     Clipper application using MAKE, you would typically have one OBJ file for
     each PRG file.  Each OBJ file "depends" on the corresponding PRG file since
     the OBJ file needs to be remade when the PRG file changes.  In other words,
     when a change is made to a program file, it needs to be recompiled to
     create a new object file.  Similarly, the EXE file "depends" on all of the
     object files that are linked together to create it.

     MAKE allows you to specify these dependencies and perform the fewest
     recompiles to completely update your system for all program changes. It can
     save an enormous amount of time on the edit-compile-link-run cycle for a
     large system development.

     NDMAKE use three files--the MAKE.EXE file itself, a MAKE.INI file that
     specifies certain defaults, and a file named MAKEFILE that contains the
     dependencies for your system.  SNAP! can create the MAKEFILE.  It is up to
     you to deal with MAKE.INI.  In particular, you will need to add a default
     rule to your MAKE.INI file to tell MAKE how to compile a PRG file into an
     OBJ file.  Its syntax is:

     # To produce a `.obj' file from a `.prg' file using Clipper.
          .prg.obj:; clipper $< -m

     This definition should work with most versions of MAKE.  If you use a
     different MAKE utility, you may need to use slightly different syntax here.
     Check your documentation to be sure.

     The SNAP! MAKE option works hand-in-hand with the LNK option.  If you ask
     SNAP! to create a LNK file, SNAP! will use the same file name when it
     create MAKEFILE.

     The net effect of all of this is that you can issue the command:

          MAKE filename   (where filename is the name of your TopFile)

     and MAKE will figure out what needs to be recompiled and linked to create
     your system.

     Sample LNK and MAKEFILE listings are included in appendix A.


     Batch Files

     SNAP! also produces DOS batch files to do useful things.  One file, named
     UPDATE.BAT, will copy all program files from the SNAP! output directory to
     the original source directory.  You could use it to copy the new
     (documented) versions of your source files over the original (undocumented)
     source files.  The syntax for UPDATE is:

          UPDATE d:



                                          36







     where d: is a drive or directory name.  If it is omitted, the original
     source directory is assumed.  Be careful with this file since it overwrites
     the original source code files.  You should backup your original files and
     review the new output files before executing UPDATE.  No kidding.  This is
     important.

     BACKPRG backs up the programs, format files and report forms in your
     system.  Its syntax is:

          BACKPRG d:

     d: is a drive or directory name and is required.  If you do not specify a
     target drive or directory, the batch file will complain and stop.

     BACKDBF backs up the databases, index files and memory files in your
     system.  Its syntax is:

          BACKDBF d:

     d: is a drive or directory name and is required.  If you do not specify a
     target drive or directory, the batch file will complain and stop.

     Macros are suppressed from this file.

     Also, SNAP! creates the PRINTDOC.BAT file to send all documentation files
     (not including source code or action diagrams) to the printer. PRINTDOC
     calls the DOS PRINT utility for background printing.  Thus, PRINT must be
     available somewhere on the path.


     Action Diagrams

     An action diagram documents the structure of a program by using graphical
     symbols to group related statements together.  By default, SNAP! uses the
     IBM extended ASCII characters in the action diagrams it prepares.


















                                          37







     A portion of a sample action diagram follows:


     ┌─IF s_clipper .AND. s0_filt = 7
     │  ╔═DO WHILE .NOT. s0_userfilt
     │  ║    SKIP
     │  ║  ┌─IF EOF()
     │  ║  │    GOTO TOP
     │  ║  │  ╔═DO WHILE .NOT. &s0_userfilt
     │  ║  │  ║    SKIP
     │  ║  │  ║  ┌─IF EOF()
     │  ║  │  ║  │    SET FILTER TO
     │  ║  │  ║  │    s0_userfilt = "1=1"
     │  ║  │  ║  │    GOTO TOP
     │  ║  │  ^═══════LOOP
     │  ║  │  ║  │  ┌─IF Dusty Day In The Lake
     │  ║  │  ║  │  │    ? "Yell and Scream"
     <═══════════════════RETURN
     │  ║  │  ║  │  └─ENDIF
     │  ║  │  ║  └─ENDIF
     │  ║  │  ╚═ENDDO
     │  ║  │  ╒═DO CASE
     │  ║  │  ╞═CASE lastkey() = 4
     │  ║  │  │    choice = "F"
     │  ║  │  ╞═CASE lastkey() = 19
     │  ║  │  │    choice ="B"
     │  ║  │  ╘═ENDCASE
     │  ║  └─ENDIF
     │  ╚═ENDDO
     │  ╓─FOR i = 1 TO 25
     │  ║    DO sample1
     │  ╙─NEXT
     └─ENDIF

     As this example shows, different extended ASCII characters are used to
     differentiate different control structures.  Loops (DO WHILE, FOR, SCAN)
     use the double-line vertical bar, while conditional statements (IF, DO
     CASE) use a single vertical bar.

     The structures are distinguished further by the horizontal symbol used to
     connect the control structure key word with the vertical bar.

     Note also that these diagrams allow you to identify "unusual" loop exits
     such as LOOP and RETURN very easily.  I can often identify subtle,
     difficult-to-locate bugs by studying the action diagram for the program.

     SNAP! will identify certain syntax errors (such as a LOOP statement that is
     not within a DO WHILE loop) only if you choose to prepare action diagrams.
     Certain error checking is only performed within this module.

     The Format screen allows you to choose whether to write action diagrams or
     not.  It also allows you to specify the extension that action diagram files

                                          38







     will have.  Action diagrams always have the same main file name (i.e, the
     first eight characters) as the source code file from which it is drawn, but
     the extension can be anything you specify except '.PRG'.  You can use the
     '?' character as a wildcard to match the corresponding characters in the
     original file extension.  Therefore, if you choose an action file extension
     of'??T', and your original source file was named FOO.BAR, the action
     diagram file will be named FOO.BAT (the BA is drawn from the original
     filename, and the T comes from the action diagram file mask).

     Action diagram files are very much like program files and have the same
     capitalization as the output program files do.  However, action diagram
     files are not directly executable or compilable because of the additional
     line-drawing characters they contain.

     Some printers (most Epson models, for example) do not support the IBM
     graphics characters very well.  If you want to print action diagrams, you
     may want to use other characters for the connections.  You can choose to
     prepare action diagrams using only ASCII symbols by choosing the ASCII
     symbol option on the source code and action diagram options screen.

     You can also choose your own action diagram symbols on the 'SourceCode and
     Action Diagram Options' screen.  The following chart shows how to customize
     the symbols:

        Default symbols: ─│┌└├═║╔╚^v═│╒╘╞─║╓╙<═

               Position: 0000000001111111111222
                         1234567890123456789012

               Position                              Symbol
               -------- -----------------------------------------------------
                   1      Horizontal symbol used for IF/ELSE/ENDIF structures
                   2      Vertical symbol used for IF/ELSE/ENDIF structures
                   3      Corner for IF and BEGIN SEQUENCE (Clipper only)
                   4      Corner for ENDIF and END (Clipper only)
                   5      Join symbol for ELSE
                   6      Horizontal symbol used for DO WHILE/ENDDO structures
                   7      Vertical symbol used for DO WHILE/ENDDO structures
                   8      Corner for DO WHILE
                   9      Corner for ENDDO
                  10      Symbol for LOOP
                  11      Symbol for EXIT and BREAK (Clipper only)
                  12      Horizontal symbol used for DO CASE/OTHERWISE/ENDCASE
                          structures
                  13      Vertical symbol used for DO CASE/OTHERWISE/ENDCASE
                          structures
                  14      Corner for DO CASE
                  15      Corner for ENDCASE
                  16      Join symbol for CASE and OTHERWISE
                  17      Horizontal symbol used for FOR/NEXT structures
                  18      Vertical symbol used for FOR/NEXT structures
                  19      Corner for FOR

                                             39







                  20      Corner for NEXT
                  21      Arrow symbol for RETURN/CANCEL/QUIT
                  22      Horizontal symbol used for RETURN/QUIT/LOOP/EXIT

     You can replace any of these symbols with others of your choosing. If you
     want to restore the default set, simply select 'G' for graphics characters,
     move to another input screen, then come back again (in simpler terms,
     select 'G', press Ctrl-PgDn then Ctrl-PgUp). These symbols are reset when
     the 'Source Code and Action Diagrams Options' screen is presented.  One
     consequence is that you must answer 'O' (for Other Symbols) to be able to
     change the action diagram symbols. If you answer 'G', then change the
     symbols, the changes will not take effect.  Like other input fields, any
     user-defined symbols will be saved in the configuration file so you do not
     have to enter them at each invocation of SNAP!

     The SCAN/ENDSCAN control structure is documented with the same symbols as
     the DO WHILE loop.  The BEGIN SEQUENCE/BREAK/END control structure is
     diagrammed with the same symbols as an IF/ENDIF structure.


     Source Code Printout

     When you have completed your program, you will probably want a listing of
     the source code to accompany the rest of your documentation.  SNAP!
     provides a facility for formatting and printing dBASE source code files
     and/or action diagrams, and gives you a great deal of control over source
     code format.  You can set the following parameters:

          Line width
          Page length
          Left and right margins
          Top and bottom margins
          Spaces per tab
          Include or suppress line numbers
          Printer setup string

     For example, you can set these values to leave plenty of room on the left
     side of the page so that your code will fit in a 3-ring binder.

     If a line of code exceeds the line width minus left and right margins,
     SNAP! will wrap it on the printout without messing up the page breaks.
     SNAP! also appropriately counts the wrapped line as one source code line,
     so that your cross-reference report still matches the printout.

     Each page of the printout contains a header showing the program name,
     system name, copyright notice, page number and date/time printed.  The
     programs are printed in alphabetical order.

     Line numbers are never added to an action diagram at print time. If you
     would like action diagrams to be printed with line numbers, choose the
     option on the format screen to add the line numbers directly to the action
     diagram file.  This is the default choice, so you ordinarily get action

                                          40







     diagrams (and printouts) with line numbers.  The restriction on adding line
     numbers at print time prevents duplicate line numbers from being printed.

     The print section of SNAP! deals harshly with nonsense. For example, if the
     sum of your left and right margins exceeds your line width, SNAP! will set
     the line width and the margins to their default values.  Similarly, SNAP!
     will reject top and bottom margins greater than page length, negative
     values, tab expansions greater than 12 spaces, and so on.

     SNAP! prints a three-line heading on each page of the printout, showing
     program name, system name, copyright holder, date, time, and page number.
     The heading begins on the line immediately following the top margin you
     specify.  Accordingly, if you use a top margin of 8 and a bottom margin of
     8, with 66-line paper only 47 lines of code will be printed on each page
     (66 lines - 8 top margin - 8 bottom margin - 3 heading).

     For those of you with HP LaserJet II printers, try the following
     parameters:
          Line width:  132             Page length:   80
          Top margin:    4             Bottom margin:  4
          Left margin:   8             Right margin:   1

     Setup string: \027E\027&l0o8D\027(10U\027(s16.6H

     The \027E at the beginning of the string resets the printer.  These
     parameters are stored in the printer definition file (see below for more
     details) and you do not have to type them in yourself.

     SNAP! allows you to enter a setup string to configure the printer for SNAP!
     (see above) and also a reset string to configure the printer after SNAP!
     has completed printing.  You would not ordinarily need to enter a reset
     string, but you might enter one if you wanted SNAP! to leave the printer
     configured in a particular way.

     When you are in the print options screen, you can press "F2--List" to
     display a scrollable list of printer defaults.  If you select one of the
     printers shown, the choices associated with it are used to update the print
     options parameters, such as setup string, line width, page length and so
     forth.  This feature means that you don't have to remember complicated
     control strings.  You can define them in the print options file and select
     them from the list.

     The printer options are stored in SNAPPRT.SNP.  It is an ASCII file that
     you can edit to add more printer definitions.  Descriptions for how to add
     a printer are included at the top of SNAPPRT.SNP itself.

     You can force a page break by including the *# SNAP FORMFEED directive at
     the point in your source code where you would like a new page to start.
     You could also just embed a CHR(12) character in the file, but SNAP! will
     keep the page numbers straight if you use the "*# SNAP FORMFEED" approach.
     Note that the formfeed directive itself is not printed.


                                          41







     By default, SNAP! prints to LPT1:  You can direct output to a different
     port or to a disk file by using the /P command line switch.  For example,
          SNAP /PLPT2:
     sends output to LPT2:
          SNAP /Pmyfile.txt
     sends output to a file named "myfile.txt".  If you are printing over a
     network, you may need to relax the timing conventions that SNAP! uses to
     tell that the printer is working correctly.  If you see timeout or "printer
     not ready" messages, try this:
          SNAP /PLPT1:(NET)


     Printing Without Documenting (Reprinting)

     You can use the source code printing facilities of SNAP! without going
     through the full time-consuming documentation process.  If you press the
     "F9--Print Now" key while viewing the Print screen, SNAP! will prompt you
     for a filename containing the names of files to print. SNAP! searches the
     file you name and prints the contents of the files listed therein.  SNAP!
     will not print a file with an extension of MEM, FRM, DBF, NDX, NTX, IDX,
     MDX, EXE, COM and other common non-ASCII X-Base names.  Also, SNAP! tries
     to figure out if a particular file is not an ASCII file and warn you about
     it before printing.

     SNAP! will not try to print from anything that isn't a filename, so the
     file you specify can contain all sorts of garbage without causing a
     problem.  The main effect of all this is that you can give the Print
     routines the name of a SNAP! REPRINT.DOC file and it will print all the
     source code in the system without going through the full SNAP!
     documentation process again.  Of course, you can create your own file
     containing filenames to print also.  You can also use this feature (and the
     DOCLIST.DOC file--just like REPRINT.DOC except it holds the names of
     documentation files instead of source code files) to print documentation
     files in a nicely formatted way.



















                                          42








                          Using SNAP! in a Batch Environment

     If you have several systems to document, you may wish to set up a batch
     file to invoke SNAP! with the appropriate parameters for each system so
     that you can come back in a week or two and find all your programs
     beautifully documented.  SNAP! supports Immediate Mode for batch
     documentation through the /X switch on the command line.  Used in
     conjunction with named configuration and macro files, you can sequentially
     document a series of dBASE systems.  SNAP! will take its input from the
     configuration files (or from CONFIG.SNP if no configuration file is named)
     and begin documenting the system immediately.  Note that you have to have
     your configuration file ready before you invoke the system.  If you do not
     specify a configuration file, SNAP! tries to use CONFIG.SNP in the current
     directory.

     For example, to document three dBASE systems without pausing for user
     input, set up a batch file with these lines:

          SNAP /x /fsystem1.snp
          SNAP /x /fsystem2.snp
          SNAP /x

     SNAP! will document the first system and take input from the SYSTEM1.SNP
     configuration file.  Then, without prompting for further user action, it
     will read SYSTEM2.SNP and begin documenting the second system.  Input for
     the third system is in the CONFIG.SNP (default name) file.  When the batch
     file is invoked, SNAP! will begin documenting and will not pause for user
     input at any point in the process.

     If an error occurs anywhere during the processing of these three systems,
     SNAP! will display an error message and stop documenting the system that
     experienced the error.  The batch file, however, will continue running and
     will move on to the next system to be documented.



















                                          43







                                     Random Notes

     These are some other thoughts that don't seem to fit anywhere else.

     If you have a file named HELP.PRG in the program directory, SNAP! assumes
     this must be a Clipper system, where 'HELP' is a magic name and documents
     the program accordingly.  SNAP! treats HELP.PRG as if it were called
     directly from TopFile.













































                                          44







                                 Program Limitations
                             and Things To Watch Out For

     SNAP! had the following design limitations when this documentation was
     written:

     Maximum program files:             1024 programs, procedures and functions
     Maximum other files:                128 of each type (e.g.databases)
     Maximum variables:                 2500 throughout the system
     Maximum key words:                 1600 words
     Maximum length of key word:          15 characters
     Maximum length of a token:           20 characters
     Maximum levels of program nesting:   20  levels
     Maximum number of database fields: 2048 throughout the system
     Maximum length of filename:          67 characters (including path)

     These limitations were current when this documentation was written.  You
     can verify them (it would be a good idea) by viewing the program
     limitations screen (Press F1 three times from the greeting screen).

     SNAP! uses about 210K of memory as "overhead."  This much is used as soon
     as the program is invoked.  It also allocates additional memory dynamically
     as it is needed.  It is a memory hog and will probably not be of much use
     if you don't have 640K.  SNAP! will put its overlay file into expanded
     memory (if enough is available) to speed things up, but will not otherwise
     take advantage of any memory above 640K.  I hope to change this in the
     future.

     SNAP! does not format FoxPro 2.0 code snippets.  Use the SNIPFMT program
     that accompanies FoxPro 2.0 for that.  It also does not document
     Clipper 5.0 code blocks.


     Legal Coding that is Prohibited by SNAP!

     I make no promises about what will happen if you run SNAP! against invalid
     X-Base syntax, but predict that the results will not be satisfying.  On the
     other hand, there are some "legal" coding techniques for X-Base that cause
     problems with SNAP!.  I have tried to keep these to a minimum, but some yet
     remain.

     You cannot use the word "END" as a variable in an assignment statement of
     the form:
          END = foo.
     SNAP! sees the 'END' (which is a valid control structure terminator in
     Clipper), treats anything else on the line as a comment, and becomes
     powerfully confused.  Using "END" in a:
          STORE foo TO end
     statement is acceptable.  You also cannot use PROCEDURE or FUNCTION (or a
     valid abbreviation of either) as a variable name.



                                          45







     SNAP! does not track control structures across program or procedure
     boundaries.  Normally, this is not a problem since you cannot start a DO
     WHILE loop in one program and finish it in another.  However, a BREAK
     statement can be in one program, while the loop it is breaking out of is in
     another file.  Thus, SNAP! does not report an error when it sees a BREAK
     statement, even if it cannot tell whether there is a loop for the BREAK to
     apply to.

     Hyphens in Filenames

     SNAP! uses treats a hyphen as a delimiter when it is scanning your source
     code to prepare the cross-reference report, since the hyphen usually means
     "subtract."  Thus, foo = bar-baz will correctly generate three
     cross-references--one for "foo", one for "bar" and one for "baz".  This
     technique breaks down when SNAP! sees "DO foo-bar."  In this case, both
     "foo" and "bar" will be cross-referenced.  Note that SNAP! will find the
     right file and continue documenting--it is only the cross-reference report
     that is misleading.


     Multiple Procedure Files

     If you use multiple procedure files and if they contain procedures that
     have the same name, SNAP! may document your system incorrectly.  SNAP! 5.0
     should be much better than previous versions about keeping these files
     straight, but it is probably still possible to confuse SNAP!.

     For example, assume you have two procedure files that are SET at different
     points in the system.  Both files contain a procedure called FOO, but FOO
     is not the same in each file.  When SNAP! searches for procedures, it will
     always find the first FOO and assume it is the one being called.  SNAP!
     does not track which procedure file is currently active and cannot
     distinguish between identically-named procedures in different procedure
     files.  This limitation has no effect on systems that use only one
     procedure file, or on systems that have multiple procedure files each
     containing uniquely-named procedures.

     Giving different things the same name (this is my other brother Daryl) is a
     bad programming habit to get into.  It is a good idea to use unique names
     for each procedure, function, procedure file and program.


     Suppressing Color

     If you do not like the colors I selected, or if they do not display
     properly on your monitor, putting the "/BW" switch on the command line will
     disable color.






                                          46







                                    Change History

     SNAP! has undergone several major changes.  The following list is not
     all-inclusive, but does hit the high points.


     Changes From Version 4.0 to Version 5.0

     I've moved.  If you need to reach me, CompuServe is still the best bet.  My
     user ID is 74025,514.  My mailing address has changed since the past
     version, however, and is shown below.

     No more "line too long."  SNAP! can now handle lines of arbitrary length,
     so long as no single physical line exceeds 255 characters.  You can combine
     as many 255-character lines as you want with continuation characters.

     Local Cross References and Memory Conservation.  Version 5.0 allows you to
     create "local" cross reference reports--cross references for each program
     and procedure file.  Local cross references use very little memory.  If you
     use local cross references, you should be able to document much larger
     systems.  For example, I had no trouble documenting a 50,000+ line SBT
     payroll system with local cross references on.  Note that local cross
     references and the regular global cross references are mutually exclusive.

     Multiple directories.  You can document programs and data files in multiple
     directories.  The top file screen prompts you for one directory for
     programs and another one for data, but you can have up to 25 program
     directories and 25 data directories.  You define new directories with the
          *# SNAP DATAPATH directory-path
     and
          *# SNAP PRGPATH directory-path
     directives.

     Sending printer output to a file.  With SNAP! 5.0, you can send printer
     output to any device, including a file or an output port (e.g., COM2:).

     Comment alignment.  You can instruct SNAP! to align "&&" comments on a
     particular column so that they all line up nicely.

     Heading Options.  You can specify the items to include in a heading.  For
     example, you can include "Called by" and exclude "Calls".


     Changes From Version 3.0 to Version 4.0

     Speed.  Version 4.0 is about 25% faster than version 3.0 if you have enough
     EMS memory to hold the 210K overlay.  If not, the speed of versions 4.0 and
     3.0 will be approximately equal.

     Memory Capacity.  Version 4.0 uses program overlays to increase the amount
     of memory available for cross referencing.  You will ordinarily get about
     50K more memory with 4.0.

                                          47







     Dialect Support.  SNAP! 4.0 now supports dBASE IV and FoxPro, as well as
     all of the previously-supported variants of the X-Base language.

     Mouse Support.  SNAP! 4.0 now fully supports mousing.  You can use the
     mouse to position the cursor, select function keys, and do pretty much
     everything else you would expect.

     Report Form and Label Documentation.  If you are using dBASE IV, SNAP! will
     automatically document the FRG and LBG files that dBASE IV produces.  These
     files are very much like program files and contain the code to implement
     the reports or labels you have defined.  SNAP! will include these files in
     the "CALLS" lists in the headings and will also include them in the tree
     diagram if you have set the tree options to display them.  SNAP! does not
     produce the full report form documentation for these files.

     UDF Recognition.  The code for detecting calls to user defined functions
     (UDFs) has been extensively revised and should now detect nearly all calls
     to UDFs, even the sneaky and underhanded ones.  For example, SNAP! now
     detects UDF calls from MEMOEDIT, DBEDIT and ACHOICE in Clipper
     applications, as well as a host of other, special, UDF situations.

     Documentation of Other Files.  Version 4.0 now tracks "other" files--files
     that don't fit into any of the categories such as databases, index files,
     etc.  Examples of other files include text files that are appended into
     memo fields, output files from "SET PRINTER TO foo.txt" statements and so
     forth.

     Printer Definition File.  SNAP! 4.0 now is distributed with a printer
     definition file, SNAPPRT.SNP, that contains parameters for some common
     printers.  It is an ASCII file and you can add new printers (or variants of
     existing printers) to the list.

     Parameters.  SNAP! now displays function and procedures parameters, if any,
     in the procedure summary.  Each procedure or function that takes a
     parameter will have the parameter line displayed next to the function name
     in the Procedures Summary report.

     Page breaks.  You can now use the "*# SNAP FORMFEED" directive to force a
     page break at a specific spot in the source code.  The "*# SNAP FORMFEED"
     directive itself is not printed.

     Program Narratives.  SNAP! 4.0 supports program narratives if they start
     with "*)" and echoes them to the HEADINGS.DOC file, suitable for use as a
     cover page for each source code file.

     Third-Party Libraries.  SNAP! 4.0 is distributed with a set of key words
     for several popular third-party function libraries.  You can instruct SNAP!
     to treat these key words as if they were part of the language, which
     improves SNAP!'s handling of capitalization, formatting and other aspects
     of your documentation.



                                          48







     PERSONAL.KEY.  You can now create a file with your own set of key words.
     "PERSONAL.KEY" is a magic name--SNAP! searches for it in the SNAP!
     subdirectory and adds anything it finds in it to the key words list.

     "*# INCLUDE" key words.  You can add a "*# INCLUDE foo" statement to
     DB4WORDS.SNP or PERSONAL.KEY to include other key words files, such as the
     third-party function library key words described above.

     Control Structure commenting.  Version 4.0 also allows you to add comments
     to the ends of control structures such as IF/ENDIF and CASE/ENDCASE.  For
     example, you can instruct SNAP! to add the IF condition after each ENDIF.
         IF foo = bar
            DO this
         ENDIF (foo = bar)    <-- SNAP! adds the "(foo = bar)"

     Reprinting source code.  You can now run SNAP!, exit the program without
     printing source code, and use the "F9--print now" option to print the
     source code later.  SNAP! now creates a REPRINT.DOC file that contains the
     names of all programs, procedures, action files and other files that are
     printed with source code.  Prior to version 4.0 it was difficult to print
     source code if you did not do it during the SNAP! documentation run.  In
     addition, SNAP! creates the DOCLIST.DOC file that contains the names of
     documentation files.  You can also use F9 to print these files.

     Changes From Version 2.0 to Version 3.0

     Speed.  Version 3.0 is be approximately 2.5 times as fast as version 2.0.
     The more procedures you use, the faster it will be. SNAP! 2.0 was
     particularly inefficient in documenting procedures.

     Source Code Printing.  You can now use the source code printing routines
     without going through the entire documentation process. When you press the
     right function key, it asks for a filename. SNAP! searches this file for
     other filenames, which it then prints.

     User Interface.  The user interface has gotten an interface-lift <guffaw>
     since the last version.  The number of option screens grew too large to be
     conveniently browsed with the facilities in version 2.  Version 3 now
     organizes all the screens underneath a main menu.  You can also select menu
     items with Alt-key combinations, without having to deal with the menu
     itself.

     Memory Usage.  SNAP! 3.0 uses some additional dynamic data structures to
     minimize wasted space.  Under normal circumstances, it should roughly
     triple the size of the application that can be accommodated by the system.
     In addition, after the conversion to Turbo Pascal 4.0, the size of the
     program itself shrank by about 20%.

     New Reports.  A system summary is now available to show:
        Lines of code
          Database and index names
          Number of program files

                                          49







          Number of procedures
        . . . and lots of other summary information.

     Arrays are recognized in the cross-reference report and are denoted with
     brackets (for Clipper) or parentheses (for FoxBASE), as appropriate (e.g.,
     FOO[100] or FOO(100,50) ), with the declared size shown.  The
     cross-reference report also lists public variables, macros and arrays
     separately.

     The report form documentation has been revised extensively (dBASE III
     only).  It now shows each of the fields in the report, displays the report
     heading, etc.  Similar documentation is now available for label forms,
     which were ignored entirely by SNAP! version 2.0.)

     The database summary now includes start and end columns for each field.
     Alias names are now usually shown with the appropriate physical database
     file in the database summary, file heading, tree, etc.

     Link files can now be created for PLINK86, Turbo C TLINK, or the Microsoft
     LINK program.  Make files continue to support NDMAKE and now also support
     the Clipper MAKE utility.

     File headings and may other reports show the date and time of last change,
     based on the file date/time stamp.

     Additional Options

     Here are some of the new things you can control:
          Suppression of blank lines in output file
          Suppression of comments in output file
          Optional extra indent under DO CASE statement
          Inclusion of DBF, NDX, MEM, FRM and LBL files in the tree
          Capitalization of key words
          Capitalization of tokens
          Temporary suspension of cross-referencing and formatting
          Leave the file date/time stamp unchanged
          Separate directories for programs and databases

     Changes Since SNAP! Version 1.0

     Practically everything.












                                          50







                             Some Administrative Matters

     Version Numbers

     In the past, I have sometimes been criticized for releasing one or more
     "maintenance" versions shortly after a major update.  I am guilty, but
     unrepentant.  In an attempt to be responsive to user suggestions and bug
     reports, I will continue to add features and fix bugs as they are reported.
     When the resulting minor changes are uploaded, the SNAP! version will
     include a letter (e.g., SNAP! version 4.00 will change to 4.00a).  In this
     example, if you have version 4.00, don't worry about downloading another
     version before 4.1 unless you need the specific features in the intervening
     versions.


     Updates and New Versions

     SNAP! is available on CompuServe.  At the time this documentation file was
     written, copies are available on the Fox (GO FOXFORUM) and Nantucket (GO
     NANFORUM) forums.

     Rather than download the large SNAP! files, you may prefer to send me a
     blank, formatted diskette (either 3.5 or 5.25 inch, but 3.5 takes longer)
     and a postage-paid diskette mailer, and I will send you the most current
     version.  My address is:
          Walter J. Kennamer
          7027 Dunstans Lane
          Toledo, Ohio   43617

     If you want me to supply the mailers, disks and postage, please enclose a
     check for $25.  This high figure is ostensibly for postage and handling,
     but is really for putting me to the trouble of buying mailers, disks and
     stamps.  I prefer programming to managing a mailing effort, so I will do
     the former cheaply but the latter only for a price.


     How to Get Support

     My CIS ID is 74025,514.  I log on nearly every day, except when I am
     traveling.  I am easiest to reach through CompuServe mail, but I also check
     in on the Fox, Ashton-Tate, and Nantucket Forums periodically.  If you have
     any suggestions about how to improve SNAP! or if you have encountered a
     bug, please let me know.

     My job requires me to travel frequently, and I am usually hard to reach by
     telephone.  You will probably have better success reaching me through
     CompuServe or by mail.






                                          51







     Association of Shareware Professionals

     I am a member of the Association of Shareware Professionals (ASP).  ASP
     wants to make sure that the shareware principle works for you.  If you are
     unable to resolve a shareware-related problem with an ASP member by
     contacting the member directly, ASP may be able to help.  The ASP Ombudsman
     can help you resolve a dispute or problem with an ASP member, but does not
     provide technical support for members' products.  Please write to the ASP
     Ombudsman at P.O. Box 5786, Bellevue, WA  98006 or send a CompuServe
     message via Easyplex to ASP Ombudsman 70007,3536.











































                                          52







                                   Acknowledgements

     Special thanks to Andy Walsh for writing several string procedures in
     assembly language for me.  Thanks to Peter Petto, Paul Ferrara and everyone
     else who helped me develop and debug SNAP!  Thanks to Pat Adams for public
     relations.  Thanks to Charles S. Galloway, for nagging me to do what I know
     I ought to.  He has contributed a great deal to SNAP! 5.0.

     Thanks to all the beta testers who helped so much with handling the last-
     minute details.  I used to mention them separately.  I don't anymore,
     though, so that they are not blamed for any of the last-minute details that
     turn out not to have been handled after all.  They know who they are.









































                                          53








                             Appendix A -- Sample Reports

     The following sample reports illustrate the formats of some SNAP! output.
     Since the documentation for a full system is voluminous, only limited
     portions of the documentation are presented here. This saves much space,
     but has the disadvantage of making some reports "out of sync."  Thus, the
     internal consistency of a complete package of documentation is missing
     here.  For example, if you try to trace the entries in the tree back to
     TODO.PRG, you will discover that they don't track since I trimmed out much
     of TODO.PRG so as to reduce the bulk of the documentation file. Similarly,
     the system summary shows a lot of databases that aren't in the DATADICT.DOC
     file.

     Of course, the best way to see sample SNAP! reports is to run it on some of
     your own programs.





































                                          54








       *:*********************************************************************
       *:
       *:        Program: TODO.PRG
       *:
       *:         System: ToDo -- To Do Management System
       *:         Author: Walter J. Kennamer
       *:      Copyright (c) 1988, Walter J. Kennamer
       *:  Last modified: 02/26/88     23:00
       *:
       *:          Calls: HELP.PRG
       *:               : F2_HANDLR        (procedure in TODOPRC.PRG)
       *:               : HELPEDIT         (procedure in TODOPRC.PRG)
       *:               : TDDEFLT.PRG
       *:               : ERRORMSG         (procedure in TODOPRC.PRG)
       *:               : SETDATE.PRG
       *:               : TDLOGO.PRG
       *:               : TDSETUP.PRG
       *:               : TDINPUT.PRG
       *:
       *:   Memory Files: ACCESSES.MEM
       *:               : DEFAULT.MEM
       *:
       *:     Documented: 03/02/88 at 18:39                 SNAP! version 3.00
       *:*********************************************************************
       PARAMETERS c_line               && command line
       *# SNAPMACRO s_tdfile   todo
       *# SNAPMACRO s_ddndx    tododd
       *# SNAPMACRO s0_adfname address
       external subject
       PUBLIC clipper,s_cmdline
       IF pcount() > 0
          s_cmdline = Alltrim(UPPER(c_line))
       ELSE
          s_cmdline = ""
       ENDIF
          .
          .
          .
       * read defaults
       USE
       IF FILE("default.mem")
          REST FROM  DEFAULT ADDITIVE
          IF s0_bw
             s0_montype = "M"
          ELSE
             s0_montype = "C"
          ENDIF
       ELSE
          DO tddeflt
       ENDIF
       DO tdinput

                                           55







       *: EOF: TODO.PRG




















































                                           56








       System Summary

       System: ToDo -- To Do Management System
       Author: Walter J. Kennamer
       03/02/88   18:56:29
       System Summary

       -------------------------------------------------------------------------


       This system has:
         8636 lines of code
           46 program files
            2 procedure files
           84 procedures and functions
           18 databases
            8 index files
            3 report forms
            0 format files
            0 label forms
            5 memory variable files
          622 cross-referenced tokens


       See the tree diagram for programs, procedures, functions and format files


                          Index          Report         Label          Memory
         Databases        Files          Forms          Forms          Files
       -------------- -------------- -------------- -------------- -------------

       HELP.DBF       HELPKEY.NTX    SUBREPT.FRM                   ACCESSES.MEM
       TODO.SKL       SUBJECT.NTX    TDSUMIN.FRM                   DEFAULT.MEM
       TODO.DBF       TODODD.NTX     TDDETIN.FRM                   LASTFILE.MEM
       SUBJECT.DBF    &NTXNAME                                     PRINTER.MEM
       ADDRESS.DBF    HISTDD.NTX                                   CLIP.MEM
       &B_FILE.DBF    PRIORITY.NDX
       NOTEPAD.DBF    DATEDUE.NDX
       PRTCODES.DBF   DATEDUE.NTX
       &FILE
       HIST.DBF
       TEMP.DBF
       &FNAME
       &BAK_NAME.DBF
       &FNAME.DBF
       AREACODE.DBF
       DATEDUE.DBF
       PRM.SKL
       ADDRESS.ASC



                                           57








       -------------------------------------------------------------------------
       SNAP! created the following documentation files:
          C:\SCRATCH\STATS.DOC
          C:\SCRATCH\TREE.DOC
          C:\SCRATCH\FILELIST.DOC
          C:\SCRATCH\NDXSUMRY.DOC
          C:\SCRATCH\DATADICT.DOC
          C:\SCRATCH\FRMSUMRY.DOC
          C:\SCRATCH\PRCSUMRY.DOC
          C:\SCRATCH\XREF.DOC
          C:\SCRATCH\TODO.LNK
          C:\SCRATCH\TODO.TLK
          C:\SCRATCH\TODO.MLK
          C:\SCRATCH\MAKEFILE
          C:\SCRATCH\ERROR.DOC
          Action diagram files
          UPDATE.BAT   to update program source files in C:\TODO
          BACKDBF.BAT  to backup databases, indexes and memory files
          BACKPRG.BAT  to backup program files, report forms and format files
          PRINTDOC.BAT to print documentation files
































                                           58








       System: ToDo -- To Do Management System
       Author: Walter J. Kennamer
       03/02/88   18:56:09
       Tree Diagram

       -------------------------------------------------------------------------

       TODO.PRG
       ├────HELP.PRG
       │    │    HELP.DBF (database)
       │    ├────SHOW_HELP (procedure in HELP.PRG)
       │    │    ├────SETCOLOR (procedure in TODOPRC.PRG)
       │    │    └────CENTER (procedure in TODOPRC.PRG)
       │    ├────SETCOLOR (procedure in TODOPRC.PRG)
       │    └────CENTER (procedure in TODOPRC.PRG)
       ├────F2_HANDLR (procedure in TODOPRC.PRG)
       │    ├────ADDRLIST.PRG
       │    │    └────SETCOLOR (procedure in TODOPRC.PRG)
       │    └────NUMLIST.PRG
       │         └────SETCOLOR (procedure in TODOPRC.PRG)
       ├────HELPEDIT (procedure in TODOPRC.PRG)
       ├────TDDEFLT.PRG
       │    ├────SETCOLOR (procedure in TODOPRC.PRG)
       │    ├────SCRHEAD (procedure in TODOPRC.PRG)
       │    │    └────SETCOLOR (procedure in TODOPRC.PRG)
       │    ├────TDSETUP.PRG
       │    │    │    TODO.SKL (database)
       │    │    │    TODO.DBF (database)
       │    │    │    SUBJECT.DBF (database)
       │    │    │    ADDRESS.DBF (database)
       │    ├────CENTER (procedure in TODOPRC.PRG)
       │    ├────SETDATE.PRG
       │    ├────SETPRT.PRG
       │    │    │    PRTCODES.DBF (database)
       │    │    ├────SCRHEAD (procedure in TODOPRC.PRG)
       │    │    │    └────SETCOLOR (procedure in TODOPRC.PRG)
       │    │    └────ERRORMSG (procedure in TODOPRC.PRG)
       │    │         ├────SETCOLOR (procedure in TODOPRC.PRG)
       │    │         └────CENTER (procedure in TODOPRC.PRG)
       │    ├────F2_HANDLR (procedure in TODOPRC.PRG)
       │    │    ├────ADDRLIST.PRG
       │    │    │    └────SETCOLOR (procedure in TODOPRC.PRG)
       │    │    └────NUMLIST.PRG
       │    │         └────SETCOLOR (procedure in TODOPRC.PRG)
       │    ├────F3_HANDLR (procedure in TODOPRC.PRG)

       and so forth





                                           59








       System: ToDo -- To Do Management System
       Author: Walter J. Kennamer
       03/02/88   18:55:52
       Procedure and Function Summary

       -------------------------------------------------------------------------

       2 procedure files in the system
          SUBJECT.PRG
          TODOPRC.PRG
       -------------------------------------------------------------------------

       SUBJECT.PRG -- Last updated:  12/30/87 at   8:47

          Contains: SUBOK()               (Params: SUBNAME)
                 Calls: SETCOLOR          (procedure in TODOPRC.PRG)
                 Calls: CENTER            (procedure in TODOPRC.PRG)
                 Calls: PUTSUB            (procedure in TODOPRC.PRG)
          Contains: SUBLOOK()             (Params: M_SUBNAME)
                 Calls: SETCOLOR          (procedure in TODOPRC.PRG)
                   .
                   .
                   .
          Contains: SUBEDIT               (Params: none)
             Called by: ED()              (function in SUBJECT.PRG)
                 Calls: SETCOLOR          (procedure in TODOPRC.PRG)

       -------------------------------------------------------------------------
       TODOPRC.PRG -- Last updated:  12/28/87 at  14:20


          Contains: F2_HANDLR             (Params: none)
             Called by: TODO.PRG
             Called by: TDDEFLT.PRG
                 Calls: ADDRLIST.PRG
                 Calls: NUMLIST.PRG
          Contains: F3_HANDLR             (Params: none)
             Called by: TODO.PRG
             Called by: TDDEFLT.PRG
                 Calls: SETCOLOR          (procedure in TODOPRC.PRG)
          Contains: F4_HANDLR             (Params: none)
             Called by: TODO.PRG
             Called by: TDDEFLT.PRG
                   .
                   .
                   .
          Contains: ISCTRL()              (Params: none)
          Contains: SCREEN_ON             (Params: none)
             Called by: ROLODEX.PRG
          Contains: PRINT_ON              (Params: none)
             Called by: ROLODEX.PRG

                                           60








       System: ToDo -- To Do Management System
       Author: Walter J. Kennamer
       03/02/88   18:55:42
       Database Structure Summary

       -------------------------------------------------------------------------

       3 databases in the system
          HELP.DBF
          TODO.DBF
          SUBJECT.DBF
       -------------------------------------------------------------------------

       Structure for database : HELP.DBF
       Number of data records :      37
                 Last updated :  09/09/87 at  11:06
       Field  Field name  Type        Width    Dec    Start      End
           1  HCALLPRG    Character       8               1        8
           2  HINPUTVAR   Character      12               9       20
           3  HSCRNNUM    Character       4              21       24
           4  HELPMSG     Memo           10              25       34
       ** Total **                       35


       This database is associated with the memo file: HELP.DBT

       This database appears to be associated with index file(s):
              : HELPKEY.NTX  (UPPER(hcallprg+hscrnnum+hinputvar))

       SNAP! did not find any associated report forms

       Used by: HELP.PRG
              : TDFIX.PRG
              : TDREINDX.PRG
              : TDREPAIR       (procedure in TDFIX.PRG)

       -------------------------------------------------------------------------


       Structure for database : TODO.DBF
       Number of data records :     112
                 Last updated :  03/01/88 at  17:35
       Field  Field name  Type        Width    Dec    Start      End
           1  ITEM        Character      55               1       55
           2  PRIORITY    Character       1              56       56
           3  DATE_DUE    Date            8              57       64
           4  CALTIME     Character       5              65       69
           5  COMPLETE    Character       1              70       70
           6  ADVANCE     Numeric         3              71       73
           7  DATE_ASGN   Date            8              74       81
           8  DATE_COMP   Date            8              82       89

                                           61







           9  LATE        Numeric         3              90       92
          10  ITEMTYPE    Character       1              93       93
          11  ALARM       Character       1              94       94
          12  SUBJECT     Character      30              95      124
          13  DURATION    Numeric         8      2      125      132
          14  VERSION     Character       5             133      137
       ** Total **                      138


       This database appears to be associated with index file(s):
              : TODODD.NTX   (DTOS(date_due)+priority+caltime)
              : DATEDUE.NDX  (index key not found)

       This database appears to be associated with multiple index file(s):
              : TODO.MDX

       SNAP! did not find any associated report forms

       Used by: TDSETUP.PRG
              : TDINPUT.PRG
              : OPENDATA       (procedure in TDSETUP.PRG)
              : EDITEXIT.PRG
              : TDREDATE.PRG
              : TDPURGE.PRG
              : TDFIX.PRG
              : TDCAL.PRG
              : TDREINDX.PRG

       -------------------------------------------------------------------------


       Structure for database : SUBJECT.DBF
       Number of data records :      41
                 Last updated :  01/12/88 at   9:34
       Field  Field name  Type        Width    Dec    Start      End
           1  SUBCODE     Character      20               1       20
           2  SUBJECT     Character      30              21       50
       ** Total **                       51


       This database appears to be associated with index file(s):
              : SUBJECT.NTX  (UPPER(subject))

       SNAP! did not find any associated report forms

       Used by: TDSETUP.PRG
              : TDINPUT.PRG
              : OPENDATA       (procedure in TDSETUP.PRG)
              : TDREINDX.PRG




                                           62







       -------------------------------------------------------------------------
       System: ToDo -- To Do Management System
       Author: Walter J. Kennamer
       03/02/88   18:55:49
       Database summary
       -------------------------------------------------------------------------

       Note: the actual system used more than 3 databases.  All but three were
       removed above to save space.  This portion of the report shows all of
       them.

       Field Name         Type    Len   Dec     Database
       ABBREV              C       2     0     AREACODE.DBF
       ADDRESS             C      53     0     ADDRESS.DBF
       ADVANCE             N       3     0     TODO.SKL
                                               TODO.DBF
                                               HIST.DBF
       ALARM               C       1     0     TODO.SKL
                                               TODO.DBF
                                               HIST.DBF
       AREACODE            N       3     0     AREACODE.DBF
       BPHONE              C      12     0     ADDRESS.DBF
       CALTIME             C       5     0     TODO.SKL
                                               TODO.DBF
                                               HIST.DBF
       CITIES              C      78     0     AREACODE.DBF
       CITY                C      25     0     ADDRESS.DBF
       COL                 N       2     0     PRTCODES.DBF
       COMMENT             C      50     0     ADDRESS.DBF
       COMPANY             C      53     0     ADDRESS.DBF
       COMPLETE            C       1     0     TODO.SKL
                                               TODO.DBF
                                               HIST.DBF
       COMPRESS            C      13     0     PRTCODES.DBF
       COUNTRY             C      20     0     ADDRESS.DBF
       DATE_ASGN           D       8     0     TODO.SKL
                                               TODO.DBF
                                               HIST.DBF
       DATE_COMP           D       8     0     TODO.SKL
                                               TODO.DBF
                                               HIST.DBF
       DATE_DUE            D       8     0     TODO.SKL
                                               TODO.DBF
                                               HIST.DBF
       DURATION            N       8     2     TODO.SKL
                                               TODO.DBF
       ELITE               C      13     0     PRTCODES.DBF
       FORMFEED            C      13     0     PRTCODES.DBF
       HCALLPRG            C       8     0     HELP.DBF
       HELPMSG             M      10     0     HELP.DBF
       HINPUTVAR           C      12     0     HELP.DBF
       HSCRNNUM            C       4     0     HELP.DBF

                                           63







       ITEM                C      55     0     TODO.SKL
                                               TODO.DBF
                                               HIST.DBF
       ITEMTYPE            C       1     0     TODO.SKL
                                               TODO.DBF
                                               HIST.DBF
       LATE                N       3     0     TODO.SKL
                                               TODO.DBF
                                               HIST.DBF
       LINE                C      78     0     TEMP.DBF
                                               PRM.SKL
       NAME                C      30     0     ADDRESS.DBF
       NAME                C      25     0     PRTCODES.DBF
       NOTES               M      10     0     ADDRESS.DBF
                                               NOTEPAD.DBF
       PHONE               C      12     0     ADDRESS.DBF
       POSITION            C      40     0     ADDRESS.DBF
       PRIORITY            C       1     0     TODO.SKL
                                               TODO.DBF
                                               HIST.DBF
       PRTNUM              N       2     0     PRTCODES.DBF
       RESET               C      13     0     PRTCODES.DBF
       ROW                 N       2     0     PRTCODES.DBF
       SECONDLINE          C      53     0     ADDRESS.DBF
       STATE               C       2     0     ADDRESS.DBF
       STATE               C      15     0     AREACODE.DBF
       SUBCODE             C      20     0     SUBJECT.DBF
       SUBJECT             C      30     0     TODO.SKL
                                               TODO.DBF
                                               SUBJECT.DBF
                                               HIST.DBF
       VERSION             C       5     0     TODO.SKL
                                               TODO.DBF
                                               NOTEPAD.DBF
       ZIP                 C      10     0     ADDRESS.DBF


















                                           64







       System: ToDo -- To Do Management System
       Author: Walter J. Kennamer
       03/02/88   18:55:15
       Index Parameter Summary

       -------------------------------------------------------------------------

       5 index files in the system
          HELPKEY.NDX
          SUBJECT.NDX
          TODODD.NDX
          &NTXNAME
          DATEDUE.NDX
       -------------------------------------------------------------------------

       HELPKEY.NTX -- Indexed on: UPPER(hcallprg+hscrnnum+hinputvar)
       Last updated:  09/09/87 at  11:06


       This index file appears to be associated with database(s):
              : HELP.DBF

       Used by: HELP.PRG
              : TDFIX.PRG
              : TDREINDX.PRG
              : TDREPAIR       (procedure in TDFIX.PRG)

       -------------------------------------------------------------------------
       SUBJECT.NTX -- Indexed on: UPPER(subject)
       Last updated:  01/12/88 at   9:16


       This index file appears to be associated with database(s):
              : SUBJECT.DBF

       Used by: SUBLOOK()      (function  in SUBJECT.PRG)
              : PART_MATCH()   (function  in SUBJECT.PRG)
              : TDSETUP.PRG
              : TDINPUT.PRG
              : OPENDATA       (procedure in TDSETUP.PRG)
              : TDFIX.PRG
              : TDREINDX.PRG
              : TDREPAIR       (procedure in TDFIX.PRG)

       -------------------------------------------------------------------------
       TODODD.NTX -- Indexed on: DTOS(date_due)+priority+caltime
       Last updated:  03/01/88 at  17:35


       This index file appears to be associated with database(s):
              : TODO.DBF


                                           65







       Used by: TDSETUP.PRG
              : TDINPUT.PRG
              : EDITEXIT.PRG
              : EDITSRCH.PRG
              : TDREDATE.PRG
              : TDPURGE.PRG
              : EDITCHGE.PRG
              : TDFIX.PRG
              : PRTUNCMP.PRG
              : TDREINDX.PRG
              : TDREPAIR       (procedure in TDFIX.PRG)

       -------------------------------------------------------------------------
       &NTXNAME is a macro unknown to SNAP!

       This index file appears to be associated with database(s):
              : ADDRESS.DBF

       Used by: TDSETUP.PRG
              : OPENDATA       (procedure in TDSETUP.PRG)
              : ADDRESS.PRG
              : TDFIX.PRG
              : TDREINDX.PRG
              : TDREPAIR       (procedure in TDFIX.PRG)
              : ADDRBOOK.PRG
              : ROLODEX.PRG

       -------------------------------------------------------------------------
       File not found--DATEDUE.NDX

       This index file appears to be associated with database(s):
              : TODO.DBF

       Used by: TDCAL.PRG
              : TDCALDAY.PRG


















                                           66







       System: ToDo -- To Do Management System
       Author: Walter J. Kennamer
       03/02/88   18:55:15
       Multiple Index Summary

       -------------------------------------------------------------------------

       1 multiple index file in the system
          TODO.MDX
       -------------------------------------------------------------------------

       TODO.MTX--Last updated:  09/09/87 at  11:06
              TAG : TDITEM  (item)
              TAG : TDPRIOR (priority+itemtype)

       This multiple index file appears to be associated with database(s):
              : TODO.DBF

       Used by: TODO.PRG


































                                           67







       System: ToDo -- To Do Management System
       Author: Walter J. Kennamer
       03/02/88   18:55:50
       Report Form File Summary

       -------------------------------------------------------------------------

       2 report forms in the system
          SUBREPT.FRM
          TDSUMIN.FRM
        ------------------------------------------------------------------------

       SUBREPT.FRM                              Last updated:  08/24/87 at  10:14
          Summary report?  No
          Eject page before printing?  No       Eject page after printing?  Yes
          Double space report?  No              Plain page?  No
          Left margin:    8                     Right Margin:    0


     -------------------------------------------------------------------------
                                        Report Contents

     -------------------------------------------------------------------------
       No.   Field                               Length    Decimals     Totaled?
       ---   ----------------------------------  ------    --------     --------

         1   Subject                                 40        0            No
         2   Subcode                                 25        0            No
                                                  -----
                                                     65
                                                  =====


          -----------------------------------------------------------------------
                                          Report Layout
          -----------------------------------------------------------------------
       Page No.     1
       00/00/00

                                                 Subject Codes

       Subject                                  Charge Code
       1                                        2

          ----------------------------------------------------------------------
                      Database and Program References
          ----------------------------------------------------------------------

          SNAP! could not find an associated database

          Used by: SUBREPT        (procedure in SUBJECT.PRG)


                                           68










       TDSUMIN.FRM                             Last updated:  09/01/87 at  15:17
          Summary report?  No
          Eject page before printing?  Yes      Eject page after printing?  Yes
          Double space report?  Yes             Plain page?  No
          Left margin:    1                     Right Margin:    0


     -------------------------------------------------------------------------
                                        Report Contents

     -------------------------------------------------------------------------
       No.   Field                               Length    Decimals     Totaled?
       ---   ----------------------------------  ------    --------     --------

         1   "______"                                 6        0            No
         2   RECNO()                                  4        0            No
         3   Item                                    55        0            No
         4   " "+dtoc(date_due)                       9        0            No
         5   Caltime                                  6        0            No
                                                  -----
                                                     80
                                                  =====


         ----------------------------------------------------------------------
                                   Report Layout
         ----------------------------------------------------------------------
       Page No.     1
       00/00/00



                                               Uncompleted Items

              No.  Item                                        Due Date  Time
              ===  =========================================== ========= =====
         1    2    3                                           4         5


          ----------------------------------------------------------------------
                      Database and Program References
          ----------------------------------------------------------------------

          SNAP! could not find an associated database

          Used by: PRTUNCMP.PRG




                                           69







       System: FoxAPP
       Author: Walter J. Kennamer
       09/04/91   08:51:49
       Screen File Summary

     -----------------------------------------------------------------------------
     --

       1 screen file in the system
          APPSCX.SCX
     -----------------------------------------------------------------------------
     --

       APPSCX.SCX           Last updated:  06/28/91 at 17:29

                               FoxPro Application Generator


        0         1         2         3         4         5
        012345678901234567890123456789012345678901234567890123456789
       0
       1     Step 1: Create or modify a database
       2      ┌───────────────────────────────────────┐
       3      │Database name:                         │
       4      │1: dbfname.............................│
       5      │< Create >    < Modify >    <File List>│
       6      └───────────────────────────────────────┘
       7
       8     Step 2 : Design a screen
       9      ┌───────────────────────────────────────┐
      10      │Screen name:                           │
      11      │5: scxname.............................│
      12      │< Create >    < Modify >    <File List>│
      13      └───────────────────────────────────────┘
      14                   «  Generate  »
      15
      16                   <   Cancel   >


     -----------------------------------------------------------------------------
     -
          Window name: Appgen
          Coordinates: FROM 0,0 TO 0,52
       Window options: FLOAT CLOSE MINIMIZE SHADOW


     -----------------------------------------------------------------------------
     -

          Name                Type           Picture



                                           70








     -----------------------------------------------------------------------------
     -

       1: dbfname             Field          "@S67"
       2: adddbf              Push button    "@*VN Create"
       3: moddbf              Push button    "@*VN Modify"
       4: Listdbf             Push button    "@*VN File List"
       5: scxname             Field          "@S67"
       6: addscx              Push button    "@*VN Create"
       7: modscx              Push button    "@*VN Modify"
       8: Listscx             Push button    "@*VN File List"
       9: generate            Push button    "@*VN \!Generate"
      10: cancbut             Push button    "@*VT \?Cancel"







































                                           71







       System: APPMENU Menu Program
       Author: Walter J. Kennamer
       09/04/91   09:53:51
       Menu File Summary

     -----------------------------------------------------------------------------
     --

       1 menu file in the system
          APPMENU.MNX
     -----------------------------------------------------------------------------
     --

       APPMENU.MNX          Last updated:  06/29/91 at 15:53

        System                                         ALT+S   (Submenu SYSTEM)
           About...                                            (Procedure)
           Help...                                     F1      _MST_HELP
           Macros                                              _MST_MACRO
           ------------                                        (Submenu
     _MST_CALCU)
           Calculator                                          _MST_CALCU
           Calendar/Diary                                      _MST_DIARY
           Puzzle                                              _MST_PUZZL
           ------------                                        (Submenu )
           Quit                                                (Procedure)
        Edit                                           ALT+E   (Submenu EDIT)
           Cut                                         CTRL+X  _MED_CUT
           Copy                                        CTRL+C  _MED_COPY
           Paste                                       CTRL+V  _MED_PASTE
           ------------                                        _MED_SP200
           Clear                                               _MED_CLEAR
           Select All                                  CTRL+A  _MED_SLCTA
           ------------                                        _MED_SP300
           Preferences...                                      _MED_PREF
        Application                                    ALT+A   (Submenu APPLIC)
           Top                                         F2      (Procedure)
           Bottom                                      F3      (Procedure)
           Next                                        F4      (Procedure)
           Prior                                       F5      (Procedure)
           ------------                                        (Submenu )
           Add record                                          (Procedure)
           Copy record                                         (Procedure)
           Delete record                               CTRL+D  (Procedure)
           ------------                                        (Submenu )
           Browse                                      CTRL+B  (Procedure)
           Search...                                   CTRL+S  (Procedure)
           Filter...                                   CTRL+F  (Procedure)
           Order...                                    CTRL+O  (Procedure)
           ------------                                        (Submenu )
           Query...                                    CTRL+Q  (Procedure)
           Report...                                   CTRL+R  DO prtopts

                                           72







        Utilities                                      ALT+U   (Submenu UTILITIES)
           Construct index                                     (Procedure)
           Pack                                                (Procedure)
           Environment                                         (Submenu ENVIRO)
              Status Bar                                       (Procedure)
              Clock                                            (Procedure)
              Extended video                                   (Procedure)
              Sticky                                           (Procedure)













































                                           73







       System: ToDo -- To Do Management System
       Author: Walter J. Kennamer
       03/02/88   18:55:58
       Token Cross-Reference Report

       ------------------------------------------------------------------------

       622 tokens are included in this report.


       Legend for context symbols:
          (blank) reference does not change the variable or field value.
          = variable or field is changed in an assignment statement.
          x variable is released.
          A array is declared.
          G GET statement changes variable or field.
          P variable is declared PUBLIC.
          R field is replaced.
          U database is USEd
          V variable is declared PRIVATE.
          & variable is referenced in a macro--takes preference over all others.
          @ variable passed as a var parameter--Clipper only
          ? reference is of unknown type.

       ABBREV
          AREACODE.PRG     90   134   178

       ABORT
          TDINPUT.PRG      62x   67P  306=
          EDITSRCH.PRG     35=   69=   99=
          EDITCHGE.PRG     32=

       ACCESSES
          TODO.PRG        130
          TDEXIT.PRG       24

          .
          .
          .

       YESNO
          ADDRESS.PRG     476=  482G  482   484   663=  664   665=  668G  668
                         748=  751G  751   753

       YR
          TDCOPY.PRG      109=  116=  116   122   126   128   224   226   241=
                         248   255   262   264   277

       ZIP
          ADDRESS.PRG     130   227   282   301R  336R  363
          ADDRBOOK.PRG     85    86    88
          ROLODEX.PRG     180   181   183

                                           74







       System: ToDo -- To Do Management System
       Author: Walter J. Kennamer
       03/02/88   18:56:06
       Public Variable Summary

       ------------------------------------------------------------------------


       These variables were declared PUBLIC somewhere in the system.
       Some may also be used as private variables in some parts of the code.

       ABORT                                   ADDR_MROW
       ANSWER                                  CARD_ROWS
       CLIPPER                                 CMD_LINE
       C_OFFSET                                DATE_STR
           .
           .
           .
       S_TESTDATE                              S_VERSION
       T_COMP                                  T_DATED
       T_DUR                                   T_ITEM
       T_ITEMTYPE                              T_PRIOR
       T_SUBJ                                  T_TIME






























                                           75







       System: ToDo -- To Do Management System
       Author: Walter J. Kennamer
       03/02/88   18:56:06
       Macro Summary

       ------------------------------------------------------------------------


          Macros Defined to SNAP!
          ----------------------------------------------------------------------

          Variable       Expansion
          -------------- ---------------------------------

          S_TDFILE        TODO
          S_DDNDX         TODODD
          S0_ADFNAME      ADDRESS

          ----------------------------------------------------------------------
          Macros Not Defined to SNAP!
          ----------------------------------------------------------------------

          &BAK_NAME                               &B_FILE
          &COLR_STR                               &FIELD1
          &FIELD2                                 &FIELD_NAME
          &FILT_STR                               &FLDNAME
          &FNAME                                  &IN_DB
          &IN_SELECT                              &IN_VAL
          &M_WORKAREA                             &NTXNAME
          &NUM                                    &PROGNAME
          &REP_FNAME                              &REV_COLR
          &S0_COLR1                               &S0_COLR2
          &S0_DATA                                &S0_PRMNAME
          &S0_PROGRAM                             &S0_USERFILT
          &SRCHFLD                                &TEMPIN

       ------------------------------------------------------------------------
       System: ToDo -- To Do Management System
       Author: Walter J. Kennamer
       03/02/88   18:56:06
       Array Summary

       ------------------------------------------------------------------------
       An array declared with a variable (e.g., DECLARE foo[bar])
       will be shown as having a size of [var].

       FIELD_LENGTH[var]
       FIELD_LIST[2]





                                           76








       System: ToDo -- To Do Management System
       Author: Walter J. Kennamer
       03/02/88   18:56:29
       File List
       ------------------------------------------------------------------------

       Programs and procedures:
         ADDRBOOK.PRG
         ADDRESS.PRG
         ADDRFILT()        (function  in ADDRESS.PRG)
         ADDRLIST.PRG
             .
             .
             .
         TIMEFORM()        (function  in TDCALDAY.PRG)
         TODO.PRG
         UNHIGHLIGHT       (procedure in SHOWCAL.PRG)
         VERPRT.PRG

       Procedure files:
         SUBJECT.PRG
         TODOPRC.PRG

       Databases:
            .
            .
            .
         HELP.DBF
         HELP.DBT
         SUBJECT.DBF
         TODO.DBF

       Index files:
         &NTXNAME
         DATEDUE.NDX
         DATEDUE.NTX
         HELPKEY.NTX
         HISTDD.NTX
         PRIORITY.NDX
         SUBJECT.NTX
         TODODD.NTX

       Report forms:
         SUBREPT.FRM
         TDDETIN.FRM
         TDSUMIN.FRM

       Memory files:
         ACCESSES.MEM
         CLIP.MEM
         DEFAULT.MEM

                                           77









                                   Index

     4PRINT  . . . . . . . . . . . . . . . . . . . . . . . . .  12, 13
     Abbreviations . . . . . . . . . . . . . . . . . . . . . . . .  10
     Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .  53
     Action diagrams . . . . . . . . . . . 4, 8, 10, 13, 20, 37-41, 58
        User-defined symbols . . . . . . . . . . . . . . . . . . .  40
     Ashton-Tate . . . . . . . . . . . . . . . . . . . . . . . . 1, 51
     Association of Shareware Professionals  . . . . . . . . . . .  52
     Backup
        Importance of  . . . . . . . . . . . . . . . . . . . . . . . 7
     Batch operation . . . . . . . . . . . . . . . . . . . . . . .  43
     Blank lines, suppression of . . . . . . . . . . . . . . . . .  22
     Break Statements  . . . . . . . . . . . . . . . . . .  20, 40, 46
     Capitalization  . . . . . .  5, 10, 18, 21-23, 34, 35, 39, 48, 50
     Change history  . . . . . . . . . . . . . . . . . . . . . . .  47
     Clipper
        Index files  . . . . . . . . .  11, 29, 42, 57, 61, 62, 65, 77
     Command line switches
        /A -- Alternate CASE indenting . . . . . . . . . . . . . .  21
        /BW -- black and white . . . . . . . . . . . . . . . . . .  46
        /F -- Configuration file name  . . . . . . . . . . . . . . . 9
        /M -- macro file name  . . . . . . . . . . . . . . . . . .  14
        /O -- omit macros  . . . . . . . . . . . . . . . . . . . .  14
        /P -- Printer port or filename . . . . . . . . . . . . . .  42
        /S -- Echo reports to screen . . . . . . . . . . . . . . .  26
        /T -- SNAP! tag (changing *#)  . . . . . . . . . . . . . .  14
        /X -- immediate mode (batch) . . . . . . . . . . . . . . .  43
     Comments
        Putting them back in, design difficulties surrounding  . .  23
        Suppression of . . . . . . . . . . . . . . . . . . . . . .  22
     Compuserve  . . . . . . . . . . . . . . . . . . . . .  47, 51, 52
     CONFIG.SNP  . . . . . . . . . . . . . . . . . . . . . . . . 9, 43
     Configuration file  . . . . . . . . . . . . . . . . 9, 10, 40, 43
        CONFIG.SNP . . . . . . . . . . . . . . . . . . . . . . . 9, 43
        Retrieving configuration settings  . . . . . . . . . . . .  10
        Saving configuration settings  . . . . . . . . . . . . . .  10
     Continuation lines  . . . . . . . . . . . . . . . . . . . . .  47
     Control structure . . . . . . . . . . . . . .  20, 38, 40, 45, 49
     Cross-reference . 4, 5, 8, 10, 17, 18, 23, 26, 32-35, 40, 46, 50,
                                                                58, 74
        Key words  . . . . . . . . . . . . . . . . . . . . . .  23, 33
        Legend . . . . . . . . . . . . . . . . . . . . . . . . . .  32
        Limitation of type flagging  . . . . . . . . . . . . . . .  33
        Limiting to PUBLIC variables . . . . . . . . . . . . . . .  35
        Numeric constants  . . . . . . . . . . . . . . . . . . . .  32
        Quoted strings excluded from . . . . . . . . . . . . . . .  32
        What is included . . . . . . . . . . . . . . . . . . . . .  32
     Database summary  . . . . . . . . . . . . .  4, 26, 28-30, 50, 63
     dBASE II  . . . . . . . . . . . . . . 1, 5, 7, 11, 24, 29, 30, 32

                                     78







     dBASE III . . . . . . . . . .  1, 5, 8, 11, 24, 29-31, 34, 35, 50
     dBASE IV  . . . . . . . . . . . . 1, 5, 8, 11, 24, 28, 31, 35, 48
     DBXL  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
     DBxWORDS.SNP  . . . . . . . . . . . . . . . . . . . . . .  21, 35
        DB2WORDS.SNP . . . . . . . . . . . . . . . . . . . . . . 7, 24
        DB3WORDS.SNP . . . . . . . . . . . . . . . . . . 8, 23, 24, 34
        DB4WORDS.SNP . . . . . . . . . . . . . . . . . . . . 8, 24, 49
     Documentation files
        Printing . . . . . . . . . . . . . . . . . . . . . . . . .  12
     Elapsed time  . . . . . . . . . . . . . . . . . . . . . . . .  10
     errors  . . . . . . . . . . . . . . . . .  11, 20, 38, 43, 46, 58
        ERROR.DOC  . . . . . . . . . . . . . . . . . . . . . .  11, 58
     Field names . . . . . . . . . . . . . . . . . . . . 21, 32, 61-63
     Format files  . . . . . 4, 10, 11, 15, 17, 19, 27, 30, 37, 57, 58
     Format screen . . . . . . . . . . . . . . .  8, 20-22, 24, 38, 40
     FoxBASE . . . . . . . . . . .  1, 5, 7, 8, 11, 24, 29, 30, 35, 50
        Index files  . . . . . . . . . . . . . . . . . . .  11, 29, 42
     FoxPro  . .  1, 4, 5, 8, 9, 11, 15-17, 24, 29, 31, 35, 45, 48, 70
     Functions
        Capitalization of function names . . . . . . . . . . .  23, 34
     Indentation . . . . . . . . . . . . . . 5, 10, 17, 18, 20, 21, 50
        Alternate CASE indenting . . . . . . . . . . . . . . . . .  21
     Index file  . . . 4, 11, 19, 28-30, 37, 48, 57, 61, 62, 65-67, 77
        NDX extensions . . . . . .  29, 30, 42, 50, 57, 62, 65, 66, 77
     Input . . . . . . . . . . . . . . . . . . . 9, 11, 19, 32, 40, 43
     Key words . . . . . . . . . . 7, 8, 10, 18, 21-24, 32, 34, 38, 45
        Capitalization . . . . .  5, 10, 18, 21-23, 34, 35, 39, 48, 50
        Cross-referencing of . . . . . . . . . . . . . . . . .  23, 32
        DBxWORDS.SNP . . . . . . . . . .  7, 8, 21, 23, 24, 34, 35, 49
        Duplicates . . . . . . . . . . . . . . . . . . . . . . . .  24
        Expansion or compression . . . . . . . . . . . . . . . . .  22
        Including other files  . . . . . . . . . . . . . . . . . .  24
        PERSONAL.KEY . . . . . . . . . . . . . . . . . . . . .  24, 49
        Peverse use of, punishment for . . . . . . . . . . . . . .  10
        Special characters in file . . . . . . . . . . . . . . . .  23
     Korenthal Associates  . . . . . . . . . . . . . . . . . .  12, 13
     Label forms . . . . . . . . . . . . . . 11, 17, 19, 26-28, 50, 57
     License agreement . . . . . . . . . . . . . . . . . . . . . . . 1
     Limitations . . . . . . . . . . . . . . . . . . . . . . . . .  45
     Link  . . . . . . . . . . . . . . . . . . . . . . . 4, 35, 36, 50
        LINK.SNP . . . . . . . . . . . . . . . . . . . . . . . . .  35
        PLINK86  . . . . . . . . . . . . . . . . . . . . . . 4, 35, 50
     MACRO.SNP . . . . . . . . . . . . . . . . . . . . . . . . . .  14
     Macros  . . . 5, 9, 14-17, 19, 28, 33, 37, 43, 50, 66, 72, 74, 76
        SNAPMACRO  . . . . . . . . . . . . . . . . . . . . . .  14, 20
     Make
        Make files . .  4, 5, 7, 8, 11, 19, 20, 22, 35, 36, 45, 50, 52
        MAKE.INI . . . . . . . . . . . . . . . . . . . . . . . . .  36
        MAKEFILE . . . . . . . . . . . . . . . . . . . . . . .  36, 58
        NDMAKE . . . . . . . . . . . . . . . . . . . . . . . . . .  36
     Memory files  .  4, 9, 11, 15, 17, 19, 26, 27, 31, 37, 55, 58, 77
     Memory requirements . . . . . . . . . . . . . . . . . . . . .  45

                                     79







     Nantucket . . . . . . . . . . . . . . . . . . . . . . . . . 1, 51
     Narratives  . . . . . . . . . . . . . . . . . . . . . . . . .  48
     NDMAKE  . . . . . . . . . . . . . . . . . . . . . . . . . . .  36
     Other screen  . . . . . . . . . . . . . . . . . . . . . . . .  11
     Output  4, 7-9, 12, 19, 22, 23, 34, 36, 37, 39, 42, 47, 48, 50, 54
     Paths . . . . . . . . . . . . . . . . 7-9, 11, 12, 15, 37, 45, 47
     PERSONAL.KEY  . . . . . . . . . . . . . . . . . . . . . .  24, 49
     PLINK86 . . . . . . . . . . . . . . . . . . . . . . . . 4, 35, 50
        LINK.SNP . . . . . . . . . . . . . . . . . . . . . . . . .  35
     Print screen  . . . . . . . . . . . . . . . . . . . . . . . .  42
        HP LaserJet II setup string  . . . . . . . . . . . . . . .  41
     Printer configuration file  . . . . . . . . . . . . . . . . .  26
     Printing documentation  . . . . . . . . . . . . . . . . . . .  12
        4PRINT . . . . . . . . . . . . . . . . . . . . . . . . . .  12
        Norton Utilities LP Program  . . . . . . . . . . . . . . .  12
        Reprinting . . . . . . . . . . . . . . . . . . . .  13, 42, 49
     PRIVATE variables . . . . . . . . . . . . . . . .  33, 35, 74, 75
     Procedure files
        Unique name requirement  . . . . . . . . . . . . . . . . .  46
     ProClip . . . . . . . . . . . . . . . . . . . . . . . . . . .  24
     Program narratives  . . . . . . . . . . . . . . . . . . . . .  48
     PUBLIC variables  . . . . . .  18, 32, 33, 35, 50, 53, 55, 74, 75
     Quicksilver . . . . . . . . . . . . . . . . . . . . . . . . 5, 11
     Recursion (see Recursion) . . . . . . . . . . . . . . . . . .  27
     Registration Fee  . . . . . . . . . . . . . . . . . . . . . . . 6
     Report forms  . 4, 10, 11, 17, 19, 26-28, 31, 37, 57, 58, 61, 62,
                                                                68, 77
     Rettig, Tom . . . . . . . . . . . . . . . . . . .  18, 22, 24, 34
     SNAP FORMAT . . . . . . . . . . . . . . . . . . . . . . . . .  18
     SNAP XREF . . . . . . . . . . . . . . . . . . . . . . . . . .  18
     SNAP.DOC  . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
     SNAP.EXE  . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
     SNAP.HLP  . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
     SNAP! directives
        Changing *#  . . . . . . . . . . . . . . . . . . . . . . .  14
        DATAPATH . . . . . . . . . . . . . . . . . . . . . . . . .  17
        FORMAT . . . . . . . . . . . . . . . . . . . . . . . . . .  18
        FORMFEED . . . . . . . . . . . . . . . . . . . . . . . . .  41
        PRGPATH  . . . . . . . . . . . . . . . . . . . . . . . . .  17
        SNAPCODE . . . . . . . . . . . . . . . . . . . . . . 15-18, 29
        SNAPMACRO  . . . . . . . . . . . . . . . . . 14-16, 18, 28, 55
        XREF . . . . . . . . . . . . . . . . . . . . . . . . . . .  18
     SNAPMACRO . . . . . . . . . . . . . . . . . . . . . . . .  14, 20
     Source code printout  . . . . . . . . . . . . . . . . . . . .  40
        Alternatives to SNAP!  . . . . . . . . . . . . . . . . . .  12
        Directing to a file or another port  . . . . . . . . . . .  42
        Forcing page breaks  . . . . . . . . . . . . . . . . . . .  41
        Network printing considerations  . . . . . . . . . . . . .  42
        Printing without documenting . . . . . . . . . . . . . . .  42
        What files are not printed . . . . . . . . . . . . . . . .  42
     Support, how to get . . . . . . . . . . . . . . . . . . . . .  51
     System screen . . . . . . . . . . . . . . . . . . . 7, 10, 15, 17

                                     80







     Tabs  . . . . . . . . . . . . . . . . . . . . . .  10, 20, 40, 41
        Spaces instead of  . . . . . . . . . . . . . . . . . . . .  20
     TLINK . . . . . . . . . . . . . . . . . . . . . . . . . 4, 35, 50
     TopFile . . . . . . . . . . . . . . . 7-9, 11, 14, 31, 36, 44, 47
        Explanation of . . . . . . . . . . . . . . . . . . . . . . . 7
     Tree screen . . . . . . . . . . . . . . . . . . . . . . . . .  27
     Turbo Linker  . . . . . . . . . . . . . . . . . . . . . 4, 35, 50
     Turbo Pascal  . . . . . . . . . . . . . . . . . . . . . . . .  49
     Updates, how to get . . . . . . . . . . . . . . . . . . . . .  51
     Version Numbers . . . . . . . . . . . . . . . . . . . . . . .  51











































                                     81